# README
go-jsonnet
This an implementation of Jsonnet in pure Go. It is feature complete but is not as heavily exercised as the Jsonnet C++ implementation. Please try it out and give feedback.
This code is known to work on Go 1.8 and above. We recommend always using the newest stable release of Go.
Installation instructions
go get github.com/sh0rez/go-jsonnet/cmd/jsonnet
Build instructions (go 1.11+)
git clone [email protected]:google/go-jsonnet.git
cd go-jsonnet
go build ./cmd/jsonnet
go build ./cmd/jsonnetfmt
To build with Bazel instead:
git clone [email protected]:google/go-jsonnet.git
cd go-jsonnet
git submodule init
git submodule update
bazel build //cmd/jsonnet
bazel build //cmd/jsonnetfmt
The resulting jsonnet program will then be available at a platform-specific path, such as bazel-bin/cmd/jsonnet/darwin_amd64_stripped/jsonnet for macOS.
Bazel also accommodates cross-compiling the program. To build the jsonnet program for various popular platforms, run the following commands:
| Target platform | Build command |
|---|---|
| Current host | bazel build //cmd/jsonnet |
| Linux | bazel build --platforms=@io_bazel_rules_go//go/toolchain:linux_amd64 //cmd/jsonnet |
| macOS | bazel build --platforms=@io_bazel_rules_go//go/toolchain:darwin_amd64 //cmd/jsonnet |
| Windows | bazel build --platforms=@io_bazel_rules_go//go/toolchain:windows_amd64 //cmd/jsonnet |
For additional target platform names, see the per-Go release definitions here in the rules_go Bazel package.
Additionally if any files were moved around, see the section Keeping the Bazel files up to date.
Running tests
./tests.sh # Also runs `go test ./...`
Running Benchmarks
Setup
go get golang.org/x/tools/cmd/benchcmp
- Make sure you build a jsonnet binary prior to making changes.
go build ./cmd/jsonnet -o jsonnet-old
- Make changes (iterate as needed), and rebuild new binary
go build ./cmd/jsonnet
- Run benchmark:
# e.g. ./benchmark.sh Builtin
./benchmark.sh <TestNameFilter>
Implementation Notes
We are generating some helper classes on types by using http://clipperhouse.github.io/gen/. Do the following to regenerate these if necessary:
go get github.com/clipperhouse/gen
go get github.com/clipperhouse/set
export PATH=$PATH:$GOPATH/bin # If you haven't already
go generate
Updating and modifying the standard library
Standard library source code is kept in cpp-jsonnet submodule, because it is shared with Jsonnet C++
implementation.
For performance reasons we perform preprocessing on the standard library, so for the changes to be visible, regeneration is necessary:
git submodule init
git submodule update
go run cmd/dumpstdlibast/dumpstdlibast.go cpp-jsonnet/stdlib/std.jsonnet > astgen/stdast.go
The above command creates the astgen/stdast.go file which puts the desugared standard library into the right data structures, which lets us avoid the parsing overhead during execution. Note that this step is not necessary to perform manually when building with Bazel; the Bazel target regenerates the astgen/stdast.go (writing it into Bazel's build sandbox directory tree) file when necessary.
Keeping the Bazel files up to date
Note that we maintain the Go-related Bazel targets with the Gazelle tool. The Go module (go.mod in the root directory) remains the primary source of truth. Gazelle analyzes both that file and the rest of the Go files in the repository to create and adjust appropriate Bazel targets for building Go packages and executable programs.
After changing any dependencies within the files covered by this Go module, it is helpful to run go mod tidy to ensure that the module declarations match the state of the Go source code. In order to synchronize the Bazel rules with material changes to the Go module, run the following command to invoke Gazelle's update-repos command:
bazel run //:gazelle -- update-repos -from_file=go.mod -to_macro=bazel/deps.bzl%jsonnet_go_dependencies
Similarly, after adding or removing Go source files, it may be necessary to synchronize the Bazel rules by running the following command:
bazel run //:gazelle