diff --git a/README.md b/README.md index 1740fd0a4..00a898ede 100644 --- a/README.md +++ b/README.md @@ -5,10 +5,12 @@ For an introduction to Jsonnet and documentation, [visit our website](https://jsonnet.org). -This repository contains the original implementation. You can also try [go-jsonnet](https://github.com/google/go-jsonnet), a newer implementation which in some cases is orders of magnitude faster. +This repository contains the original implementation. You can also try [go-jsonnet](https://github.com/google/go-jsonnet), a newer implementation which in some cases is orders of magnitude faster, and is recommended in preference to the C++ version. Visit our [discussion forum](https://groups.google.com/g/jsonnet). +**Security note:** If you need to process *untrusted inputs* (untrusted Jsonnet code), it is best not to use the C++ implementation, as it is not hardened for that use-case. The expected use-case is for evaluating Jsonnet code that you / your organisation has written and trusts not to be malicious. + ## Packages Jsonnet is available on Homebrew: diff --git a/doc/articles/fractal.1.html b/doc/articles/fractal.1.html index 98123a120..abb7fc143 100644 --- a/doc/articles/fractal.1.html +++ b/doc/articles/fractal.1.html @@ -82,9 +82,8 @@

Example Web Application

The example application allows the user to zoom and pan a Mandelbrot fractal (dynamically rendered server side, in C++). The user is able to save the location of features they find, deep in the fractal, and a time-ordered list of these with thumbnails is displayed in the - left hand pane. The application is provisionally hosted here, but you can easily deploy your own as all - required files are available in the Jsonnet repository. + left hand pane. All required files are available in the Jsonnet repository if you want to + deploy this yourself.

Although admittedly a little contrived, this example is intended to represent the structure diff --git a/doc/learning/getting_started.html b/doc/learning/getting_started.html index 90ae4b410..88ce2ed1e 100644 --- a/doc/learning/getting_started.html +++ b/doc/learning/getting_started.html @@ -274,7 +274,7 @@

YAML Stream Output

-

C++ or Go?

+

C++, Go, or others?

@@ -284,58 +284,20 @@

C++ or Go?

- There are two feature-compatible implementations of the Jsonnet interpreter. The first one - we built was the C++ interpreter, and it is still the most mature / widely used. The new Go - implementation has the benefits of simpler code (due to leveraging goroutines and the GO - garbage collector). Our long term plan is to migrate everyone to the Go implementation - eventually. Both implementations are tested against the same test suite (which is quite - thorough). Please report any deviations. The performance of the C++ implementation is - currently a bit better, but for most people this should not be a factor and we're intending - to address it over time, anyway. + There are multiple implementations of the Jsonnet interpreter. The original interpreter was + written in C++. However, there is a newer implementation written in Go, and this generally + has better performance, as well as the benefits of being written in a memory safe language. + The Go implementation also includes a linter, which is not available in the C++ implementation. + Both the C++ and Go versions are tested against the same test suite.

- Another factor is that the formatter is currently only implemented in the C++ repo, and the - linter is only implemented in the Go repo. + Beyond the 'official' C++ and Go implementations, there are also various implementations written + independently by other people, such as Rust and Haskell implementations, along with language + bindings / wrappers for some other languages (such as PHP, and JavaScript). + These are listed on the Bindings page.

- -
-
-
-

JavaScript

-
-
-
-
- -
-
-
-

- The C++ implementation can be compiled with emscripten to produce a JavaScript - implementation of Jsonnet. This is how we implement the interactive demos on this site. A - native implementation of Jsonnet in JavaScript would probably be faster. In fact, a - GopherJs transpile of the Go Jsonnet implementation may work better as well. However, the - emscripten version is easy to build, and is sufficient for many purposes. -

- -

- To compile it, first install - emscripten and ensure em++ and emcc are in your path. Then make libjsonnet.js. -

- -

- An unofficial nodejs package - of Jsonnet is also available. -

- -
-
-
-