.TH JPM 1 .SH NAME jpm \- the Janet Project Manager, a build tool for Janet .SH SYNOPSIS .B jpm [\fB\-\-flag ...\fR] [\fB\-\-option=value ...\fR] .IR command .IR args ... .SH DESCRIPTION jpm is the build tool that ships with a standard Janet install. It 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). .SH 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 .SH FLAGS .TP .BR \-\-nocolor Disable color in the jpm debug repl. .TP .BR \-\-verbose Print detailed messages of what jpm is doing, including compilation commands and other shell commands. .TP .BR \-\-test If passed to jpm install, runs tests before installing. Will run tests recursively on dependencies. .TP .BR \-\-offline Prevents jpm from going to network to get dependencies - all dependencies should be in the cache or this command will fail. Use this flag with the deps and update-pkgs subcommands. This is not a surefire way to prevent a build script from accessing the network, for example, a build script that invokes curl will still have network access. .TP .BR \-\-auto\-shebang Prepends installed scripts with a generated shebang line, such that they will use a janet binary located in JANET_BINPATH. .SH OPTIONS .TP .BR \-\-modpath=/some/path Set the path to install modules to. Defaults to $JANET_MODPATH, $JANET_PATH, or (dyn :syspath) in that order. You most likely don't need this. .TP .BR \-\-headerpath=/some/path Set the path the jpm will include when building C source code. This lets you specify the location of janet.h and janetconf.h on your system. On a normal install, this option is not needed. .TP .BR \-\-binpath=/some/path Set the path that jpm will install scripts and standalone executables to. Executables defined via declare-execuatble or scripts declared via declare-binscript will be installed here when jpm install is run. Defaults to $JANET_BINPATH, or a reasonable default for the system. See JANET_BINPATH for more. .TP .BR \-\-libpath=/some/path Sets the path jpm will use to look for libjanet.a for building standalone executables. libjanet.so is \fBnot\fR used for building native modules or standalone executables, only for linking into applications that want to embed janet as a dynamic module. Linking statically might be a better idea, even in that case. Defaults to $JANET_LIBPATH, or a reasonable default. See JANET_LIBPATH for more. .TP .BR \-\-compiler=$CC Sets the C compiler used for compiling native modules and standalone executables. Defaults to cc. .TP .BR \-\-cpp\-compiler=$CXX Sets the C++ compiler used for compiling native modules and standalone executables. Defaults to c++.. .TP .BR \-\-linker Sets the linker used to create native modules and executables. Only used on windows, where it defaults to link.exe. .TP .BR \-\-pkglist=https://github.com/janet-lang/pkgs.git Sets the git repository for the package listing used to resolve shorthand package names. .TP .BR \-\-archiver=$AR Sets the command used for creating static libraries, use for linking into the standalone executable. Native modules are compiled twice, once a normal native module (shared object), and once as an archive. Defaults to ar. .SH COMMANDS .TP .BR help Shows the usage text and exits immediately. .TP .BR build Builds all artifacts specified in the project.janet file in the current directory. Artifacts will be created in the ./build/ directory. .TP .BR install\ [\fBrepo...\fR] 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. .TP .BR uninstall\ [\fBname...\fR] 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. .TP .BR clean Remove all artifacts created by jpm. This just deletes the build folder. .TP .BR 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. .TP .BR 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. .TP .BR 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. .TP .BR list-installed List all installed packages in the current syspath. .TP .BR list-pkgs\ [\fBsearch\fR] 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. .TP .BR 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. .TP .BR run\ [\fBrule\fR] 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. .TP .BR rules List all rules that can be run via run. This is useful for exploring rules in the project. .TP .BR rule-tree\ [\fBroot\fR]\ [\fBdepth\fR] 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. .TP .BR show-paths Show all of the paths used when installing and building artifacts. .TP .BR update-pkgs Update the package listing by installing the 'pkgs' package. Same as jpm install pkgs .TP .BR quickbin\ [\fBentry\fR]\ [\fBexecutable\fR] 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. .TP .BR 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. .TP .BR make-lockfile\ [\fBfilename\fR] 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. .TP .BR load-lockfile\ [\fBfilename\fR] 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. .SH ENVIRONMENT .B JANET_PATH .RS 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) .RE .B JANET_MODPATH .RS 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. .RE .B JANET_HEADERPATH .RS 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 /../include/janet. The --headerpath=/some/path option will override this variable. .RE .B JANET_LIBPATH .RS 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 /../lib. The --libpath=/some/path option will override this variable. .RE .B JANET_BINPATH .RS The directory where jpm will install binary scripts and executables to. Defaults to (dyn :syspath)/bin The --binpath=/some/path will override this variable. .RE .B JANET_PKGLIST .RS The git repository URL that contains a listing of packages. This allows installing packages with shortnames, 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. .RE .B JANET_GIT .RS 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. .RE .B JPM_OS_WHICH .RS Use this option to override the C compiler and build system auto-detection for the host operating system. For example, set this environment variable to "posix" to make sure that on platforms like MinGW, you will use GCC instead of MSVC. On most platforms, users will not need to set this environment variable. Set this to one of the following strings: .IP \- windows .IP \- macos .IP \- linux .IP \- freebsd .IP \- openbsd .IP \- netbsd .IP \- bsd .IP \- posix .RE .SH AUTHOR Written by Calvin Rose