jsonnet.md

Jsonnet Rules

These are build rules for working with Jsonnet files with Bazel.

Setup

To use the Jsonnet rules as part of your Bazel project, please follow the instructions on the releases page.

jsonnet_library

load("@rules_jsonnet//jsonnet:docs.bzl", "jsonnet_library")

jsonnet_library(name, deps, srcs, data, imports)

Creates a logical set of Jsonnet files.

Example: Suppose you have the following directory structure:

[workspace]/
    MODULE.bazel
    configs/
        BUILD
        backend.jsonnet
        frontend.jsonnet

You can use the jsonnet_library rule to build a collection of .jsonnet files that can be imported by other .jsonnet files as dependencies:

configs/BUILD:

load("@rules_jsonnet//jsonnet:jsonnet.bzl", "jsonnet_library")

jsonnet_library(
    name = "configs",
    srcs = [
        "backend.jsonnet",
        "frontend.jsonnet",
    ],
)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
deps	List of targets that are required by the srcs Jsonnet files.	List of labels	optional	[]
srcs	List of .jsonnet files that comprises this Jsonnet library	List of labels	optional	[]
data	-	List of labels	optional	[]
imports	List of import -J flags to be passed to the jsonnet compiler.	List of strings	optional	[]

jsonnet_to_json

load("@rules_jsonnet//jsonnet:docs.bzl", "jsonnet_to_json")

jsonnet_to_json(name, deps, src, data, outs, code_vars, ext_code, ext_code_envs, ext_code_file_vars,
                ext_code_files, ext_str_envs, ext_str_file_vars, ext_str_files, ext_strs, extra_args,
                imports, multiple_outputs, out_dir, stamp_keys, tla_code, tla_code_envs,
                tla_code_files, tla_str_envs, tla_str_files, tla_strs, vars, yaml_stream)

Compiles Jsonnet code to JSON.

Example:

Example

Suppose you have the following directory structure:

[workspace]/
    MODULE.bazel
    workflows/
        BUILD
        workflow.libsonnet
        wordcount.jsonnet
        intersection.jsonnet

Say that workflow.libsonnet is a base configuration library for a workflow scheduling system and wordcount.jsonnet and intersection.jsonnet both import workflow.libsonnet to define workflows for performing a wordcount and intersection of two files, respectively.

First, create a jsonnet_library target with workflow.libsonnet:

workflows/BUILD:

load("@rules_jsonnet//jsonnet:jsonnet.bzl", "jsonnet_library")

jsonnet_library(
    name = "workflow",
    srcs = ["workflow.libsonnet"],
)

To compile wordcount.jsonnet and intersection.jsonnet to JSON, define two jsonnet_to_json targets:

jsonnet_to_json(
    name = "wordcount",
    src = "wordcount.jsonnet",
    outs = ["wordcount.json"],
    deps = [":workflow"],
)

jsonnet_to_json(
    name = "intersection",
    src = "intersection.jsonnet",
    outs = ["intersection.json"],
    deps = [":workflow"],
)

Example: Multiple output files

To use Jsonnet's multiple output files, suppose you add a file shell-workflows.jsonnet that imports wordcount.jsonnet and intersection.jsonnet:

workflows/shell-workflows.jsonnet:

local wordcount = import "workflows/wordcount.jsonnet";
local intersection = import "workflows/intersection.jsonnet";

{
  "wordcount-workflow.json": wordcount,
  "intersection-workflow.json": intersection,
}

To compile shell-workflows.jsonnet into the two JSON files, wordcount-workflow.json and intersection-workflow.json, first create a jsonnet_library target containing the two files that shell-workflows.jsonnet depends on:

jsonnet_library(
    name = "shell-workflows-lib",
    srcs = [
        "wordcount.jsonnet",
        "intersection.jsonnet",
    ],
    deps = [":workflow"],
)

Then, create a jsonnet_to_json target and set outs to the list of output files to indicate that multiple output JSON files are generated:

jsonnet_to_json(
    name = "shell-workflows",
    src = "shell-workflows.jsonnet",
    deps = [":shell-workflows-lib"],
    outs = [
        "wordcount-workflow.json",
        "intersection-workflow.json",
    ],
)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
deps	List of targets that are required by the srcs Jsonnet files.	List of labels	optional	[]
src	The .jsonnet file to convert to JSON.	Label	optional	None
data	-	List of labels	optional	[]
outs	Names of the output .json files to be generated by this rule. If you are generating only a single JSON file and are not using jsonnet multiple output files, then this attribute should only contain the file name of the JSON file you are generating. If you are generating multiple JSON files using jsonnet multiple file output (jsonnet -m), then list the file names of all the JSON files to be generated. The file names specified here must match the file names specified in your src Jsonnet file. For the case where multiple file output is used but only for generating one output file, set the multiple_outputs attribute to 1 to explicitly enable the -m flag for multiple file output. This attribute is incompatible with out_dir.	List of labels	optional	[]
code_vars	Deprecated (use 'ext_code').	Dictionary: String -> String	optional	{}
ext_code	-	Dictionary: String -> String	optional	{}
ext_code_envs	-	List of strings	optional	[]
ext_code_file_vars	-	List of strings	optional	[]
ext_code_files	-	List of labels	optional	[]
ext_str_envs	-	List of strings	optional	[]
ext_str_file_vars	-	List of strings	optional	[]
ext_str_files	-	List of labels	optional	[]
ext_strs	-	Dictionary: String -> String	optional	{}
extra_args	Additional command line arguments for the Jsonnet interpreter. For example, setting this argument to ["--string"] causes the interpreter to manifest the output file(s) as plain text instead of JSON.	List of strings	optional	[]
imports	List of import -J flags to be passed to the jsonnet compiler.	List of strings	optional	[]
multiple_outputs	Set to True to explicitly enable multiple file output via the jsonnet -m flag. This is used for the case where multiple file output is used but only for generating a single output file. For example: local foo = import "foo.jsonnet"; { "foo.json": foo, } This attribute is incompatible with out_dir.	Boolean	optional	False
out_dir	Name of the directory where output files are stored. If the names of output files are not known up front, this option can be used to write all output files to a single directory artifact. Files in this directory cannot be referenced individually. This attribute is incompatible with outs and multiple_outputs.	String	optional	""
stamp_keys	-	List of strings	optional	[]
tla_code	-	Dictionary: String -> String	optional	{}
tla_code_envs	-	List of strings	optional	[]
tla_code_files	-	Dictionary: Label -> String	optional	{}
tla_str_envs	-	List of strings	optional	[]
tla_str_files	-	Dictionary: Label -> String	optional	{}
tla_strs	-	Dictionary: String -> String	optional	{}
vars	Deprecated (use 'ext_strs').	Dictionary: String -> String	optional	{}
yaml_stream	-	Boolean	optional	False

jsonnet_to_json_test

load("@rules_jsonnet//jsonnet:docs.bzl", "jsonnet_to_json_test")

jsonnet_to_json_test(name, deps, src, data, canonicalize_golden, code_vars, error, ext_code,
                     ext_code_envs, ext_code_file_vars, ext_code_files, ext_str_envs,
                     ext_str_file_vars, ext_str_files, ext_strs, extra_args, golden, imports,
                     output_file_contents, regex, stamp_keys, tla_code, tla_code_envs, tla_code_files,
                     tla_str_envs, tla_str_files, tla_strs, vars, yaml_stream)

Compiles Jsonnet code to JSON and checks the output.

Example: Suppose you have the following directory structure:

[workspace]/
    MODULE.bazel
    config/
        BUILD
        base_config.libsonnet
        test_config.jsonnet
        test_config.json

Suppose that base_config.libsonnet is a library Jsonnet file, containing the base configuration for a service. Suppose that test_config.jsonnet is a test configuration file that is used to test base_config.jsonnet, and test_config.json is the expected JSON output from compiling test_config.jsonnet.

The jsonnet_to_json_test rule can be used to verify that compiling a Jsonnet file produces the expected JSON output. Simply define a jsonnet_to_json_test target and provide the input test Jsonnet file and the golden file containing the expected JSON output:

config/BUILD:

load(
    "@rules_jsonnet//jsonnet:jsonnet.bzl",
    "jsonnet_library",
    "jsonnet_to_json_test",
)

jsonnet_library(
    name = "base_config",
    srcs = ["base_config.libsonnet"],
)

jsonnet_to_json_test(
    name = "test_config_test",
    src = "test_config",
    deps = [":base_config"],
    golden = "test_config.json",
)

To run the test: bazel test //config:test_config_test

Example: Negative tests

Suppose you have the following directory structure:

[workspace]/
    MODULE.bazel
    config/
        BUILD
        base_config.libsonnet
        invalid_config.jsonnet
        invalid_config.output

Suppose that invalid_config.jsonnet is a Jsonnet file used to verify that an invalid config triggers an assertion in base_config.jsonnet, and invalid_config.output is the expected error output.

The jsonnet_to_json_test rule can be used to verify that compiling a Jsonnet file results in an expected error code and error output. Simply define a jsonnet_to_json_test target and provide the input test Jsonnet file, the expected error code in the error attribute, and the golden file containing the expected error output:

config/BUILD:

load(
    "@rules_jsonnet//jsonnet:jsonnet.bzl",
    "jsonnet_library",
    "jsonnet_to_json_test",
)

jsonnet_library(
    name = "base_config",
    srcs = ["base_config.libsonnet"],
)

jsonnet_to_json_test(
    name = "invalid_config_test",
    src = "invalid_config",
    deps = [":base_config"],
    golden = "invalid_config.output",
    error = 1,
)

To run the test: bazel test //config:invalid_config_test

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
deps	List of targets that are required by the srcs Jsonnet files.	List of labels	optional	[]
src	The .jsonnet file to convert to JSON.	Label	optional	None
data	-	List of labels	optional	[]
canonicalize_golden	-	Boolean	optional	True
code_vars	Deprecated (use 'ext_code').	Dictionary: String -> String	optional	{}
error	The expected error code from running jsonnet on src.	Integer	optional	0
ext_code	-	Dictionary: String -> String	optional	{}
ext_code_envs	-	List of strings	optional	[]
ext_code_file_vars	-	List of strings	optional	[]
ext_code_files	-	List of labels	optional	[]
ext_str_envs	-	List of strings	optional	[]
ext_str_file_vars	-	List of strings	optional	[]
ext_str_files	-	List of labels	optional	[]
ext_strs	-	Dictionary: String -> String	optional	{}
extra_args	Additional command line arguments for the Jsonnet interpreter. For example, setting this argument to ["--string"] causes the interpreter to manifest the output file(s) as plain text instead of JSON.	List of strings	optional	[]
golden	The expected (combined stdout and stderr) output to compare to the output of running jsonnet on src.	Label	optional	None
imports	List of import -J flags to be passed to the jsonnet compiler.	List of strings	optional	[]
output_file_contents	-	Boolean	optional	True
regex	Set to 1 if golden contains a regex used to match the output of running jsonnet on src.	Boolean	optional	False
stamp_keys	-	List of strings	optional	[]
tla_code	-	Dictionary: String -> String	optional	{}
tla_code_envs	-	List of strings	optional	[]
tla_code_files	-	Dictionary: Label -> String	optional	{}
tla_str_envs	-	List of strings	optional	[]
tla_str_files	-	Dictionary: Label -> String	optional	{}
tla_strs	-	Dictionary: String -> String	optional	{}
vars	Deprecated (use 'ext_strs').	Dictionary: String -> String	optional	{}
yaml_stream	-	Boolean	optional	False

jsonnet_toolchain

load("@rules_jsonnet//jsonnet:docs.bzl", "jsonnet_toolchain")

jsonnet_toolchain(name, compiler, create_directory_flags, manifest_file_support)

The Jsonnet compiler information.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
compiler	-	Label	optional	None
create_directory_flags	The flags passed to the Jsonnet compiler when a directory must be created.	List of strings	required
manifest_file_support	If the Jsonnet compiler supports writing the output filenames to a manifest file.	Boolean	required