Janet Packaging

project.janet & jpm ("legacy bundles")

A self-contained unit of Janet source code as recognized by jpm is called a project. A project is a directory containing a project.janet file, which contains build recipes. Often, a project will correspond to a single git repository, and contain a single library. However, a project's project.janet file can contain build recipes for as many libraries, native extensions, and executables as it wants. Each of these recipes builds an artifact. Artifacts are the output files that will either be distributed or installed on the end-user or developer's machine.

project.janet format is informal and is just a slightly modified janet script - bakpakin

Absolute minimum requirement is (declare-project :name "blah").

• declare-project can have further k:v pairs:

  • :name string (jpm will use this e.g. for jpm uninstall) (this is not what (import ...) uses)
  • :description a string
  • :dependencies an array of strings, urls to git repos with required artifacts
  • jpm will check :url then :repo
  • unactionable metadata (?) some use:
    • :url
    • :repo
    • :version

• (declare-source :source ... )

  • :source file-name(s) (this is what (import ...) uses!)
  • :prefix - will create a directory in <syspath> to put the source files in (and import will use this as its target)
  • examples
    • doesn't use source https://github.com/sogaiu/git-some-janets/blob/f76d75086a4576d58c5ed4be84e208b010093895/project.janet
    • https://github.com/sogaiu/janet-termsize/blob/96d5e3c36c8d14960f488c7aacc0f10589b86e18/project.janet

• (declare-native ...)

  • :name
  • :source array of file names as strings
  • :embedded array of file names as strings
  • :cflags - example: https://github.com/sogaiu/janet-pcg-random/blob/6c531fd9060a9fa26467cd4a3552dd88f02a8d63/project.janet
  • :headers

• (declare-executable ...)

  • :name
  • :entry filename string
  • :install boolean

• (declare-bin ...)

  • :main path executable's installed to

• (declare-binscript ... ) declares a janet file installed as executable script

  • hardcode-syspath bool - if true, inserts code so it'll run even if JANET_PATH changes
  • :is-janet bool - if true, inserts a shebang line if jpm has :auto-shebang set true
  • example: https://github.com/ianthehenry/judge/blob/3b921850006200a31b015558a72b8a62672eac8e/project.janet

• (declare-headers...)

  • :headers - path
  • :prefix

• (declare-manpage ...)

Spork has a pretty complicated project.janet file.

Here is an example which builds the legacy project.janet from the modern bundle's info.jdn.

In project.janet, I think and (declare-project :name ...) are the minimal requirements, and ... everything else is not significant to the tooling (e.g. license or version)?

jpm is currently used by the vast majority of projects.

Clojure's leinigen inspired jpm but Bakpakin et al. find jpm's declarative pproach wanting, so it's being replaced with janet-pm and modern bundles resembling Clojure's tools.build where "your build is a program" (which Zig also likes) - but you have to write that program:

The philosophy behind tools.build is that your project build is inherently a program - a series of instructions to create one or more project artifacts from your project source files. We want to write this program with our favorite programming language, Clojure, and tools.build is a library of functions commonly needed for builds that can be connected together in flexible ways. Writing a build program does take a bit more code than other declarative approaches, but can be easily extended or customized far into the future, creating a build that grows with your project.

Modern Bundles

janet-pm is spork/pm

• info.jdn or bundle/info.jdn
  • :name is required
• bundle/init.janet or bundle.janet which Pyrmont calls "bundle script"

janet-pm seems to use :jpm-dependencies and :dependencies at points

Jeep builds on top of modern bundles (instead of? or on top of janet-pm?) For Jeep, in info.jdn these fields are significant:

• :url and :repo provide URLs for jeep-new
• :dependencies https://github.com/pyrmont/jeep/blob/53b484eb7a071faa4d2c9646940096aa75a8ddc4/lib/install.janet#L53