Janet Programming Language

The Makefile requires GNU-flavored make. Follow these steps to build, test, and install:

cd somewhere/my/projects/janet
make
make test
make repl
make install

Optional: To install Spork or JPM from git, use make install-spork-git or make install-jpm-git.

1. Install Visual Studio or Visual Studio Build Tools.
2. Open a Visual Studio Command Prompt (ensure cl.exe and link.exe are in your PATH).
3. Navigate to the Janet directory.
4. Run build_win to compile.
5. Run build_win test to verify the build.

To create an .msi installer:

1. Install WiX 3.14 Toolset and add it to your PATH.
2. Run build_win dist.
3. Use build_win install to install the resulting .msi or execute the file directly.

Janet has two companion projects that are optional but useful:

• Spork: A collection of utility modules and scripts (like janet-format, janet-netrepl, and janet-pm). It requires a C compiler. On POSIX systems, scripts are installed to $JANET_PATH/bin/ by default.
• JPM: An older, opinionable project manager tool. It is more stable on some systems but less flexible and is not receiving frequent updates. It installs to /usr/local/bin/ on POSIX systems by default.

You can install them from source using the provided Make targets: make install-spork-git or make install-jpm-git.

Janet can be embedded into host C programs using an amalgamated source file.

1. Locate Files: Use build/c/janet.c (the amalgamated source), src/include/janet.h, and src/conf/janetconf.h.
2. Compilation Requirements:
   • Compile with -std=c99.
   • Link with the math library (-lm) and the dynamic linker (-ldl) to support dynamic modules.
3. Disable Dynamic Modules: If you do not need dynamic modules, add the -DJANET_NO_DYNAMIC_MODULES define to your compiler options.

You can enable shell completions for the janet interpreter in Bash using one of the following methods:

Temporary (Current session only)

Source the script directly in your current terminal session:

source /path/to/janet.bash

Permanent (System-wide)

Copy the script to the system-wide bash-completion directory (requires sudo):

sudo cp janet.bash /etc/bash_completion.d/janet

Permanent (User only)

Copy the script to your local user completions directory:

cp janet.bash ~/.local/share/bash-completion/completions/janet

You can interact with Janet via a REPL (Read-Eval-Print Loop) or by running individual scripts.

• Launch REPL: Run the janet binary with no arguments.
• Run a script: Use ./janet myscript.janet.
• Explore bindings: Inside the REPL, run (all-bindings) to print a list of all available macros, functions, and constants.

$ janet
janet:1:> (+ 1 2 3)
6
janet:2:> (print "Hello, World!")
Hello, World!
nil

On FreeBSD, you must use gmake to compile. Alternatively, you can install the pre-built package using pkg install lang/janet.

gmake
gmake test
gmake repl
gmake install

You can access documentation in two ways:

1. Online: Use the official introduction for tutorials and the core API doc for full function references.
2. In the REPL: Use the (doc symbol-name) macro to view documentation for a specific symbol. For example, (doc apply) will show the documentation for the apply function. To see all bound symbols in the current environment, use (all-bindings) or call (doc) with no arguments.

To enable completions in the Fish shell, copy the janet.fish script to your Fish completions directory:

cp janet.fish ~/.config/fish/completions/janet.fish

Meson is a cross-platform build system that provides better IDE integration and support for cross-compilation. It requires Python.

git clone https://github.com/janet-lang/janet.git
cd janet
meson setup build \
          --buildtype release \
          --optimization 2 \
          --libdir /usr/local/lib \
          -Dgit_hash=$(git log --pretty=format:'%h' -n 1)
ninja -C build

# Run the binary
build/janet

# Installation
ninja -C build install

To fuzz the unmarshaller, you must have afl and xterm installed. This process requires generating specific unmarshal test cases before running the fuzzer.

1. Generate the unmarshal test cases using Janet.
2. Prepare the fuzzing environment.
3. Set the NFUZZ environment variable to 1.
4. Run the fuzzer for the unmarshal target.
5. Once finished (Ctrl+C), aggregate the discovered test cases.
6. View the aggregated results in ./fuzz_out/unmarshal_aggregated/.

$ janet ./tools/afl/generate_unmarshal_testcases.janet
$ sh ./tools/afl/prepare_to_fuzz.sh
$ export NFUZZ=1
$ sh ./tools/afl/fuzz.sh unmarshal
# Ctrl+C to stop
$ sh ./tools/afl/aggregate_cases.sh unmarshal
$ ls ./fuzz_out/unmarshal_aggregated/

To fuzz the Janet parser, you must have afl and xterm installed. Follow these steps to prepare the environment, run the fuzzer, and aggregate the results. Note that afl may require system configuration; if it quits prematurely, run it manually to diagnose errors.

1. Prepare the fuzzing environment.
2. Set the NFUZZ environment variable to 1.
3. Run the fuzzer for the parser target.
4. Once finished (Ctrl+C), aggregate the discovered test cases.
5. View the aggregated results in ./fuzz_out/parser_aggregated/.

$ sh ./tools/afl/prepare_to_fuzz.sh
$ export NFUZZ=1
$ sh ./tools/afl/fuzz.sh parser
# Ctrl+C to stop
$ sh ./tools/afl/aggregate_cases.sh parser
$ ls ./fuzz_out/parser_aggregated/