JPM(1)

📦 version 1.2.0, in arch rolling, nixos 26.05, nixpkgs unstable

JPM(1) — the Janet Project Manager, a build tool for Janet 💅✨

Okay bestie, so jpm is literally the Janet Project Manager — a build tool for Janet — and it's about to be your new fave. The manual page name is JPM(1) (General Commands Manual, if you're keeping score), and I'm gonna walk you through the whole thing, no cap.

✨ SYNOPSIS ✨

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

Like, you give it flags, you give it --option=value pairs, you give it a command, and you give it args. That's the whole vibe. Periodt.

🌸 DESCRIPTION 🌸

So jpm is used for building Janet projects, installing dependencies, installing projects, building native modules, and exporting your Janet project to a standalone executable. I know, iconic multitasker behavior. Although it's not required for working with Janet, it removes like so much of the boilerplate with installing dependencies and building native modules. Think of it as your main character project manager.

Real talk though — jpm requires only janet to run, and it uses git to install dependencies. And yes, bestie, jpm will work without git installed. 🫶

🎀 DOCUMENTATION 🎀

So jpm has several subcommands, each used for managing either a single Janet project or all Janet modules installed on the system. Global commands — the ones that manage modules at the system level — do things like install and uninstall packages, as well as clear the cache. But the more interesting ones 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. iykyk.

👑 COMMANDS 👑

  • help — Shows the usage text and exits immediately. Like a little goodbye wave. 👋
  • build — Builds all artifacts specified in the project.janet file in the current directory. Artifacts will be created in the ./build/ directory. Slay.
  • 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. (Yes, "relase" — that's literally how it's spelled in the original, don't come for me. 😭)
  • 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. Obsessed with the efficiency.
  • 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. ("packges" is also literally how it's spelled. We keep the typos, they're part of the lore. 💀)
  • 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. Read that again bestie — the name, not the URL. 🙈
  • clean — Remove all artifacts created by jpm. This just deletes the build folder. Simple, clean, fresh start energy. 🧚
  • 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. No vibes-based grading here, it's all about that 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. Heads up: it's giving "you're on your own for conflict resolution."
  • 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. Global queen behavior. 👑
  • 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. Search bar, but make it terminal. 🔍
  • 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. Okay this one is highkey dangerous, bestie — treat it like the "delete system32" of jpm. ⚠️
  • 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. Very make-coded of it.
  • rules — List all rules that can be run via run. This is useful for exploring rules in the project. Little peek behind the curtain. 🦋
  • 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. Trust — give it a root rule, the full tree is long long. 😭
  • show-paths — Show all of the paths used when installing and building artifacts. The receipts, basically. 🧾
  • update-pkgs — Update the package listing by installing the 'pkgs' package. Same as jpm install pkgs. Two ways, one vibe.
  • 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. Standalone executable arc, we love to see it. 🔥
  • repl — Run a repl in the same environment as the test environment. Allows you to use built natives without installing them. Bestie REPL. 💖
  • 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. For when you gotta go under the hood. ("it's" is in the original too — we don't fix grammar here, we preserve facts.) 🫶
  • 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. Snapshot of your dependency era. 📸
  • 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. The other half of the lockfile duo. ✨
  • 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". C plus Janet, a collab we didn't know we needed.
  • new-exe-project [name] — Create a new project for an executable in a directory "name".

🌈 ENVIRONMENT 🌈

Okay these env vars are the glue holding the whole operation together. Learn them, love them.

  • 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. One var to rule them all. 👑
  • 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). Literally the one that matters most.
  • 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. Fancy install separation, we stan.
  • 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. (Read that carefully bestie — make those dirs first! Also yes, "that directories" is the original wording, we keep it. 💀)
  • 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. Convenience with a side of dependency control. 🎀
  • 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. If it ain't broke. 🧚
  • JANET_JPM_CONFIG — An optional path to a config file to load. This option is overridden by the --config-file command line option. Command line stays winning. ⭐

💜 AUTHOR 💜

Written by Calvin Rose <calsrose@gmail.com>. An absolute legend, we thank him for his service. 🫶

Okay bestie, that's the whole manual — every flag, every command, every env var, every single detail, preserved like the crown jewels. Now go forth and build something iconic. 🌈✨

This was JPM(1) from the General Commands Manual — page version JPM(1), and yes, that footer appears both at the top and the bottom, because symmetry. No date was listed on this page, so no date to give, sorry bestie. 💖

📦 where this page comes from