Janet 1.42.0-dev-7fd75f3 Documentation
(Other Versions: 1.42.0 1.41.2 1.41.1 1.40.1 1.40.0 1.39.1 1.38.0 1.37.1 1.36.0 1.35.0 1.34.0 1.31.0 1.29.1 1.28.0 1.27.0 1.26.0 1.25.1 1.24.0 1.23.0 1.22.0 1.21.0 1.20.0 1.19.0 1.18.1 1.17.1 1.16.1 1.15.0 1.13.1 1.12.2 1.11.1 1.10.1 1.9.1 1.8.1 1.7.0 1.6.0 1.5.1 1.5.0 1.4.0 1.3.1 )

Building Projects with Spork

Spork includes a program janet-pm that can be used to build software with C extensions, install packages, and install dependencies. The janet-pm program is compatible with older projects authored for JPM in most cases, and is able to read both project.janet files as well as the newer "bundle" spec built into the interpreter.

Building Projects inside Virtual Environments

Virtual environments are a convenient way to build software in Janet that is both broadly encompassing and will not pollute your system too much - A virtual environment can be removed simply by deleting it. It will also allow you to avoid accidentally including system versions of install libraries and scripts when building or using your programs. It is a wrapper around creating directories and setting both PATH and JANET_PATH such that everything in the environment is self contained and all dependent programs and libraries are available on on the Janet syspath.

# Create a new virtual env
$ janet-pm env venv
created project shell environment at venv
(PowerShell) run `. venv/bin/activate.ps1` to enter the new environment, then `deactivate` to exit.
(CMD)        run `venv\bin\activate` to enter the new environment, then `deactivate` to exit.
(Unix sh)    run `. venv/bin/activate` to enter the new environment, then `deactivate` to exit.

# Set up JANET_PATH and PATH for development
$ . venv/bin/activate

# Build and test
$ cd my-project
$ janet-pm deps
$ janet-pm build
$ janet-pm install
$ janet-pm test

# Make sure it worked!
$ janet -l my-project
$ my-project --help

# Clean up
$ deactivate
$ cd ..
$ rm -rf venv

"Full" Virtual Environments

By default, a virtual environment will still reference and use the global installation of an interpreter. However, the "full-env" command to janet-pm will copy the interpreter, shared objects, headers, into the virtual environment and use that instead. This allows for multiple versions of Janet on a system and provides more isolation even than a default virtual env.

$ janet-pm full-env venv

Building projects without Virtual Environments

While virtual environments are convenient, they are not completely needed for clean local builds that don't touch root-owned or system directories.

The JANET_PATH environment variable is used to determine where janet-pm will install to, as it internally wraps the bundle/ module inside Janet's core library. This means that by setting the JANET_PATH environment variable, you will be able to install

# Set up a local syspath. Both janet and janet-pm will use this for dependencies.
export JANET_PATH=$HOME/my-janet-path
mkdir $JANET_PATH

# Build and test
cd my-project
janet-pm deps
janet-pm build
janet-pm install
janet-pm test

# Use a library
janet -l my-project -e "(print :hi)"

# clean up
rm -rf "$JANET_PATH"
unset JANET_PATH
export JANET_PATH

Virtual environments wrap this flow with a few other conveniences.

Note that many projects will require running tests after installation. This makes it convenient to build and test software inside a virtual environment.

Global installation (requires sudo access!)

If JANET_PATH is unset or explicitly set to root-owned directory like /usr/local/lib/janet then janet-pm will attempt to use the default syspath location for installing bundles, which is usally a global installation. You can check with janet -e "(print (dyn *syspath*))".

If you are comfortable installing some piece of Janet software globally on your machine, or if your are working inside a container, janet-pm will handle global installation as well. The one caveat is that by default, executable programs and scripts will not be installed on your PATH but will be installed under "<syspath>/bin". This directory can then optionally be symlinked to or added to your PATH.

cd my-project
sudo janet-pm deps
janet-pm build
sudo janet-pm install
janet-pm test

(On Windows, sudo is not required. Use of sudo on POSIX systems depends on whether you installed janet to a directory owned by the root user.)

Unless you need really this, prefer virtual environments or local builds. Simply setting JANET_PATH to something in your home directory will likely avoid some of these issues.