1# Jsonnet Sandboxed API 2 3This library was sandboxed as part of Google's summer 2020 internship program 4([blog post](https://security.googleblog.com/2020/12/improving-open-source-security-during.html)). 5 6This directory contains a sandbox for the 7[Jsonnet](https://github.com/google/jsonnet) library. 8 9## How to use from an existing Project 10 11If your project does not include Sandboxed API as a dependency yet, add the 12following lines to the main `CMakeLists.txt`: 13 14```cmake 15include(FetchContent) 16 17FetchContent_Declare(sandboxed-api 18 GIT_REPOSITORY https://github.com/google/sandboxed-api 19 GIT_TAG main # Or pin a specific commit/tag 20) 21FetchContent_MakeAvailable(sandboxed-api) # CMake 3.14 or higher 22 23add_sapi_subdirectory(contrib/jsonnet) 24``` 25 26The `add_sapi_subdirectory()` macro sets up the source and binary directories 27for the sandboxed jsonnet targets. 28 29Afterwards your project's code can link to `sapi_contrib::jsonnet` and use the 30corresponding header `contrib/jsonnet/jsonnet_base_sandbox.h`. 31 32## Examples 33 34The `examples/` directory contains code to produce three command-line tools -- 35`jsonnet_sandboxed`, `jsonnet_yaml_stream_sandboxed` and 36`jsonnet_multiple_files_sandboxed` to evaluate jsonnet code. The first one 37enables the user to evaluate jsonnet code held in one file and writing to one 38output file. The second evaluates one jsonnet file into one file, which can be 39interepreted as YAML stream. The third one is for evaluating one jsonnet file 40into multiple output files. All three tools are based on what can be found 41[here](https://github.com/google/jsonnet/blob/master/cmd/jsonnet.cpp). 42 43Apart from these, there is also a file producing `jsonnet_formatter_sandboxed` 44executable. It is based on a tool found from 45[here](https://github.com/google/jsonnet/blob/master/cmd/jsonnetfmt.cpp). It is 46a jsonnet code formatter -- it changes poorly written jsonnet files into their 47canonical form. 48 49### Build as part of Sandboxed API 50 51To build these examples, after cloning the whole Sandbox API project, run this 52in the `contrib/jsonnet` directory: 53 54``` 55mkdir -p build && cd build 56cmake .. -G Ninja -Wno-dev -DSAPI_BUILD_TESTING=ON 57ninja 58``` 59 60To run `jsonnet_sandboxed` (or `jsonnet_yaml_stream_sandboxed` or 61`jsonnet_formatter_sandboxed` in a similar way): 62 63``` 64cd examples 65./jsonnet_sandboxed \ 66 absolute/path/to/the/input_file.jsonnet \ 67 absolute/path/to/the/output_file 68``` 69 70To run `jsonnet_mutiple_files_sandboxed`: 71 72``` 73cd examples 74./jsonnet_mutiple_files_sandboxed \ 75 absolute/path/to/the/input_file.jsonnet \ 76 absolute/path/to/the/output_directory 77``` 78 79All three tools support evaluating one input file (possibly relying on multiple 80other files, e.x. by jsonnet `import` command; the files must be held in the 81same directory as input file) into one or more output files. Example jsonnet 82codes to evaluate in a one-in-one-out manner can be found 83[here](https://github.com/google/jsonnet/tree/master/examples). Example code 84producing multiple output files or YAML stream files can be found in the 85`examples/jsonnet_codes` directory (along with some other examples copied with 86minimal changes from the library files), in files called 87`multiple_files_example.jsonnet` and `yaml_stream_example.jsonnet`, 88respectively. In the `examples/jsonnet_codes_expected_output` directory one can 89found outputs the mentioned above files' evaluation should produce. 90 91The formatter reads one input file and produces one output file as a result. 92Example code for this tool can also be found in `examples/jsonnet_codes` 93directory, in a file called `formatter_example.jsonnet`. 94 95### Running the tests 96 97A few tests prepared with a use of 98[Google Test](https://github.com/google/googletest) framework are included. To 99run them type: 100 101``` 102ctest -R JsonnetTest. 103``` 104