Getting Started

Install J2, run a program, and meet the tools you will use day to day. Ten minutes, start to finish.

Install

J2 0.1.0 ships for macOS on Apple Silicon as a signed and notarized bundle. The quickest route is the package installer from the download page: open it, click through, done. It installs J2 under /usr/local/j2 and puts the j2 command on your PATH.

If you prefer to keep things in your home directory, use the tarball instead:

$ tar xzf j2-0.1.0-aarch64-apple-darwin.tar.gz
$ cd j2-0.1.0-aarch64-apple-darwin
$ ./install.sh

Either way, open a new terminal and confirm the install:

$ j2 --version
j2 0.1.0

The bundle is self contained. It includes the interpreter, the native compiler, and every library the compiler links against, so nothing else needs to be installed and no network access is ever required to build a program. The one exception is the system linker used by native builds: if you have never installed the Xcode Command Line Tools, run xcode-select --install once.

Run a program

Put this in hello.j2:

print("hello, world")

and run it:

$ j2 run hello.j2
hello, world

j2 run executes the program through the interpreter. It starts in milliseconds and touches no compiler, which makes it the right mode for scripts and for the tight loop of writing code. The bare form j2 hello.j2 does the same thing with one extra trick: if the program uses something the interpreter cannot handle, it quietly compiles natively and runs that instead.

Build for speed

When a program does real computation, compile it:

$ j2 build simulate.j2 -o simulate
$ ./simulate

The result is a standalone native binary. Beyond ordinary compiled speed, the build step recognizes loops and independent function calls that are provably safe to run in parallel and spreads them across your CPU cores automatically. Nothing in your source changes; see Automatic Parallelism for what qualifies.

The REPL

Start an interactive session with j2 repl. Definitions and bindings persist across lines, expressions print their value, and :quit exits.

$ j2 repl
j> x = 6 * 7
j> print(x)
42
j> :quit

Each line is compiled natively behind a build cache, so the first line pays a short warm-up and the rest are quick.

Editor support

A Visual Studio Code extension ships with each release. It adds syntax highlighting for .j2 files, a run command on Cmd+Shift+R, and inline error squiggles on save. Grab j2-lang-0.1.0.vsix from the download page and install it:

$ code --install-extension j2-lang-0.1.0.vsix

A complete first program

Here is a small program that exercises a function, a loop, and conditionals. The range 1..n includes both endpoints:

# fizzbuzz up to n
func fizzbuzz(n) = {
    for i in 1..n {
        if i % 15 == 0 { print("fizzbuzz") }
        else if i % 3 == 0 { print("fizz") }
        else if i % 5 == 0 { print("buzz") }
        else { print(i) }
    }
}

fizzbuzz(20)

Where to go next

Read the language chapters in order, starting with Program Structure; they build on each other and cover the entire language. If you learn best by reference, the Standard Library and Command Line pages are the two you will keep open.

PreviousIntroduction NextProgram Structure