---
layout: default
title: Getting Started
---

<div class="hgroup">
  <div class="hgroup-inline">
    <div class="panel">
      <h1 id="getting-started">Getting Started</h1>
    </div>
    <div style="clear: both"></div>
  </div>
</div>

<div class="hgroup">
  <div class="hgroup-inline">
    <div class="panel">
      <p>
        While the <a href="/learning/tutorial.html">tutorial</a> is the introduction to the language
        itself, this page helps you get started with the implementations.  If you want to link
        Jsonnet as a library, see <a href="/ref/bindings.html">bindings</a>.
      </p>
    </div>
    <div style="clear: both"></div>
  </div>
</div>

<div class="hgroup">
  <div class="hgroup-inline">
    <div class="panel">
      <h2 id="interpreters">Interpreters</h2>
    </div>
    <div style="clear: both"></div>
  </div>
</div>

<div class="hgroup">
  <div class="hgroup-inline">
    <div class="panel">
      <p>
        The easiest way to execute some Jsonnet code is invoking an interpreter via the commandline
        as so:
      </p>
      <pre>jsonnet -e &lt;code&gt;</pre>
      <p>
        Or a filename:
      </p>
      <pre>jsonnet &lt;file&gt;</pre>
      <p>
        This dumps the JSON on stdout.  The tool is self-documenting with <tt>--help</tt>.  You can
        experiment with the Jsonnet files in the <a
        href="https://github.com/google/jsonnet/tree/master/examples">examples/</a> directory of the
        C++ Github repo.
      </p>
      <p>
        To get Jsonnet, you can build it from either the <a
        href="https://github.com/google/jsonnet">C++</a> or the <a
        href="https://github.com/google/go-jsonnet">Go</a> repositories.  See below for the
        differences between them.  Each repo has a README.md containing build instructions.
      </p>
    </div>
    <div style="clear: both"></div>
  </div>
</div>


<div class="hgroup">
  <div class="hgroup-inline">
    <div class="panel">
      <h3 id="example">Example</h3>
    </div>
    <div style="clear: both"></div>
  </div>
</div>

<div class="hgroup">
  <div class="hgroup-inline">
    <div class="panel">
      <p>Evaluating a file.</p>

      <pre>$ jsonnet landingpage.jsonnet
{
   "person1": {
      "name": "Alice",
      "welcome": "Hello Alice!"
   },
   "person2": {
      "name": "Bob",
      "welcome": "Hello Bob!"
   }
}</pre>

      <p>Evaluating a snippet.</p>

      <pre>$ jsonnet -e '{ x: 1 , y: self.x + 1 } { x: 10 }'
{
   "x": 10,
   "y": 11
}</pre>
    </div>
    <div style="clear: both"></div>
  </div>
</div>


<div class="hgroup">
  <div class="hgroup-inline">
    <div class="panel">
      <h3 id="multi">Multiple File Output</h3>
    </div>
    <div style="clear: both"></div>
  </div>
</div>


<div class="hgroup">
  <div class="hgroup-inline">
    <div class="panel">
      <p>
        The Jsonnet commandline tool has a special mode for generating multiple JSON files from a
        single Jsonnet file.  This can be useful if you want to avoid writing lots of small Jsonnet
        files, or if you want to take advantage of cross-references and interdependencies between
        the files.  The idea is to create a single JSON structure, the top level of which defines
        the various files:
      </p>

      <pre>// multiple_output.jsonnet
{
  "a.json": {
    x: 1,
    y: $["b.json"].y,
  },
  "b.json": {
    x: $["a.json"].x,
    y: 2,
  },
}</pre>

      <p>
        When executed using <tt>jsonnet -m &lt;dir&gt;</tt>, this will write the generated JSON to
        files <tt>a.json</tt> and <tt>b.json</tt> in the given directory, instead of the whole thing
        being written to stdout.  In order to integrate nicely with build tools like <tt>make</tt>,
        the files are not touched if they already contain the given content.  To stdout is printed
        the list of target files, one per line.  This makes it easy to drive other tools that
        operate on the JSON files, e.g. via <tt>xarg</tt>.
      </p>

      <pre>$ jsonnet -m . multiple_output.jsonnet
a.json
b.json
$ cat a.json 
{
   "x": 1,
   "y": 2
}
$ cat b.json 
{
   "x": 1,
   "y": 2
}</pre>

    </div>
    <div style="clear: both"></div>
  </div>
</div>


<div class="hgroup">
  <div class="hgroup-inline">
    <div class="panel">
      <h3 id="stream">YAML Stream Output</h3>
    </div>
    <div style="clear: both"></div>
  </div>
</div>


<div class="hgroup">
  <div class="hgroup-inline">
    <div class="panel">
      <p>
        Unlike JSON, YAML can represent several objects in the same file, separated by <tt>---</tt>.
        The Jsonnet commandline parameter <tt>-y</tt> causes the tool to expect the Jsonnet
        execution to yield an array.  Config designed for this mode typically looks like this:
        It then outputs that array as a sequence of JSON documents
        separated by <tt>---</tt>, which any YAML parser will interpret as a YAML stream.
      </p>
      <pre>// yaml_stream.jsonnet
local
  a = {
    x: 1,
    y: b.y,
  },
  b = {
    x: a.x,
    y: 2,
  };

[a, b]</pre>
      <p>
        When executed using <tt>-y</tt>, this will output that array as a sequence of JSON documents
        separated by <tt>---</tt> and terminated with <tt>...</tt>.  Any YAML parser <i>should</i>
        interpret this as a YAML stream (people have reported broken parsers, so try it out first).
      </p>
      <pre>$ jsonnet -y . yaml_stream.jsonnet
---
{
   "x": 1,
   "y": 2
}
---
{
   "x": 1,
   "y": 2
}
...</pre>
    </div>
    <div style="clear: both"></div>
  </div>
</div>


<div class="hgroup">
  <div class="hgroup-inline">
    <div class="panel">
      <h2 id="cpp-or-go">C++ or Go?</h2>
    </div>
    <div style="clear: both"></div>
  </div>
</div>

<div class="hgroup">
  <div class="hgroup-inline">
    <div class="panel">
      <p>
        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.
      </p>
      <p>
        Another factor is that the formatter is currently only implemented in the C++ repo, and the
        linter is only implemented in the Go repo.
      </p>
    </div>
    <div style="clear: both"></div>
  </div>
</div>


<div class="hgroup">
  <div class="hgroup-inline">
    <div class="panel">
      <h2 id="javascript">JavaScript</h2>
    </div>
    <div style="clear: both"></div>
  </div>
</div>

<div class="hgroup">
  <div class="hgroup-inline">
    <div class="panel">
      <p>
        The C++ implementation can be compiled with <a
        href="http://kripken.github.io/emscripten-site/">emscripten</a> 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.
      </p>

      <p>
        To compile it, first <a
        href="http://kripken.github.io/emscripten-site/docs/getting_started/downloads.html">install
        </a> emscripten and ensure em++ and emcc are in your path.  Then make libjsonnet.js.
      </p>

      <p>
        An unofficial <a href="https://github.com/yosuke-furukawa/node-jsonnet">nodejs package</a>
        of Jsonnet is also available.
      </p>

    </div>
    <div style="clear: both"></div>
  </div>
</div>