JPM(1) User Commands JPM(1)

NAME

jpm - the Janet Project Manager, a build tool for Janet

SYNOPSIS

jpm [--flag ...] [--option=value ...] command args...

DESCRIPTION

jpm is used for building Janet projects, installing dependencies,
installing projects, building native modules, and exporting your
Janet project to a standalone executable. Although not required for
working with Janet, it removes much of the boilerplate with
installing dependencies and building native modules. jpm requires
only janet to run, and uses git to install dependencies (jpm will
work without git installed).

DOCUMENTATION

jpm has several subcommands, each used for managing either a single
Janet project or all Janet modules installed on the system. Global
commands, those that manage modules at the system level, do things
like install and uninstall packages, as well as clear the cache.
More interesting are the local commands. For more information on jpm
usage, see https://janet-lang.org/docs/index.html

For information on flags, see the usage documentation in the tool.

COMMANDS

help Shows the usage text and exits immediately.


build Builds all artifacts specified in the project.janet file in
the current directory. Artifacts will be created in the
./build/ directory.


configure[path]
Create a directory for out-of-tree builds, and also set
project options. While jpm does not require an explicit
configure step, this can be used to avoid needing to set the
same options repeatedly. Out of tree builds are also a
convenient way to have multiple configurations at the same
time, such as a relase build and a debug build.


install [repo...]
When run with no arguments, installs all installable artifacts
in the current project to the current JANET_MODPATH for
modules and JANET_BINPATH for executables and scripts. Can
also take an optional git repository URL and will install all
artifacts in that repository instead. When run with an
argument, install does not need to be run from a jpm project
directory. Will also install multiple dependencies in one
command.

update-installed
Update to the latest version of all installed packges. Will do
this by reinstalling from source control with latest available
tag for each bundle. May overwrite any bundles that have been
installed to a specific tag.


uninstall [name...]
Uninstall a project installed with install. uninstall expects
the name of the project, not the repository url, path to
installed file, or executable name. The name of the project
must be specified at the top of the project.janet file in the
declare-project form. If no name is given, uninstalls the
current project if installed. Will also uninstall multiple
packages in one command.


clean Remove all artifacts created by jpm. This just deletes the
build folder.


test Runs jpm tests. jpm will run all janet source files in the
test directory as tests. A test is considered failing if it
exits with a non-zero exit code.


deps Install all dependencies that this project requires
recursively. jpm does not resolve dependency issues, like
conflicting versions of the same module are required, or
different modules with the same name. Dependencies are
installed with git, so deps requires git to be on the PATH.


clear-cache
jpm caches git repositories that are needed to install modules
from a remote source in a global cache ($JANET_PATH/.cache).
If these dependencies are out of date or too large, clear-
cache will remove the cache and jpm will rebuild it when
needed. clear-cache is a global command, so a project.janet is
not required.


list-installed
List all installed packages in the current syspath.


list-pkgs [search]
List all package aliases in the current package listing that
contain the given search string. If no search string is
given, prints the entire listing.


clear-manifest
jpm creates a manifest directory that contains a list of all
installed files. By deleting this directory, jpm will think
that nothing is installed and will try reinstalling everything
on the jpm deps or jpm load-lockfile commands. Be careful with
this command, as it may leave extra files on your system and
shouldn't be needed most of the time in a healthy install.


run [rule]
Run a given rule defined in project.janet. Project definitions
files (project.janet) usually contain a few artifact
declarations, which set up rules that jpm can then resolve, or
execute. A project.janet can also create custom rules to
create arbitrary files or run arbitrary code, much like make.
run will run a single rule or build a single file.


rules List all rules that can be run via run. This is useful for
exploring rules in the project.


rule-tree [root] [depth]
Show rule dependency tree in a pretty format. Optionally
provide a rule to use as the tree root, as well as a max depth
to print. By default, prints the full tree for all rules. This
can be quite long, so it is recommended to give a root rule.


show-paths
Show all of the paths used when installing and building
artifacts.


update-pkgs
Update the package listing by installing the 'pkgs' package.
Same as jpm install pkgs


quickbin [entry] [executable]
Create a standalone, statically linked executable from a Janet
source file that contains a main function. The main function
is the entry point of the program and will receive command
line arguments as function arguments. The entry file can
import other modules, including native C modules, and jpm will
attempt to include the dependencies into the generated
executable.


repl Run a repl in the same environment as the test environment.
Allows you to use built natives without installing them.


debug-repl
Load the current project.janet file and start a repl in it's
environment. This lets a user better debug the project file,
as well as run rules manually.


make-lockfile [filename]
Create a lockfile. A lockfile is a record that describes what
dependencies were installed at the time of the lockfile's
creation, including exact versions. A lockfile can then be
later used to set up that environment on a different machine
via load-lockfile. By default, the lockfile is created at
lockfile.jdn, although any path can be used.


load-lockfile [filename]
Install dependencies from a lockfile previously created with
make-lockfile. By default, will look for a lockfile at
lockfile.jdn, although any path can be used.


new-project [name]
Create a new Janet project interactively in a directory
"name".


new-c-project [name]
Create a new C+Janet project interactively in a directory
"name".


new-exe-project [name]
Create a new project for an executable in a directory "name".

ENVIRONMENT

JANET_TREE
A convenient way to set the modpath, binpath, syspath, and
manpath all at once. This is equivalent to the --tree
parameter to jpm.

JANET_PATH
The location to look for Janet libraries. This is the only
environment variable Janet needs to find native and source
code modules. If no JANET_PATH is set, Janet will look in the
default location set at compile time, which can be determined
with (dyn :syspath)

JANET_MODPATH
The location that jpm will use to install libraries to.
Defaults to JANET_PATH, but you could set this to a different
directory if you want to. Doing so would let you import Janet
modules on the normal system path (JANET_PATH or (dyn
:syspath)), but install to a different directory. It is also a
more reliable way to install. This variable is overwritten by
the --modpath=/some/path if it is provided.

JANET_HEADERPATH
The location that jpm will look for janet header files
(janet.h and janetconf.h) that are used to build native
modules and standalone executables. If janet.h and janetconf.h
are available as default includes on your system, this value
is not required. If not provided, will default to <jpm script
location>/../include/janet. The --headerpath=/some/path option
will override this variable.

JANET_LIBPATH
Similar to JANET_HEADERPATH, this path is where jpm will look
for libjanet.a for creating standalone executables. This does
not need to be set on a normal install. If not provided, this
will default to <jpm script location>/../lib. The
--libpath=/some/path option will override this variable.

JANET_BINPATH
The directory where jpm will install binary scripts and
executables to. Defaults to (dyn :syspath)/bin The
--binpath=/some/path will override this variable.

JANET_BUILDPATH
The directory where jpm will put intermediate files, object
code, and compiled executables. Defaults to ./build The
--buildpath=/some/path will override this variable. You should
make that directories above this directory exist before
building.

JANET_PKGLIST
The git repository URL that contains a listing of packages.
This allows installing packages with short names, which is
mostly a convenience. However, package dependencies can use
short names, package listings can be used to choose a
particular set of dependency versions for a whole project.

JANET_GIT
An optional path to a git executable to use to clone git
dependencies. By default, uses "git" on the current $PATH. You
shouldn't need to set this if you have a normal install of
git.

JANET_JPM_CONFIG
An optional path to a config file to load. This option is
overridden by the --config-file command line option.

AUTHOR

Written by Calvin Rose <calsrose@gmail.com>

JPM(1)