Anatomy of a package

A manifest answers five questions: what the package is, where its versions come from, where its files come from, how they install, and what it needs and gives. The Quickstart manifest is the running example; the exact rule for each key is on the pkg.yaml reference.

Identity

schema: 3
name: jq
description: Command-line JSON processor
homepage: https://jqlang.org
license: MIT

schema is 3. Catalogs still carrying 2 load; nem catalog fmt rewrites it. name is what people type after nem use, and it must match the directory the manifest lives in. description is shown by nem search and nem info, homepage and license by nem info, and nothing else depends on them.

Older versions can keep an earlier recipe in a frozen sibling file; see Frozen recipes.

Where versions come from

versionDiscovery:
  github:
    repo: jqlang/jq
    filter: '^jq-\d+\.\d+(\.\d+)?$'
    prefix: "jq-"

Optional, but it is what lets nem catalog outdated notice a new upstream release and nem catalog bump add it with checksums. Without it, new versions are typed by hand. See Version discovery.

Where files come from

artifact:
  url: "https://github.com/jqlang/jq/releases/download/jq-{{.Version}}/jq-{{replace .OS \"darwin\" \"macos\"}}-{{.Arch}}"

One download per version and platform. A template turns nem's names for the OS and architecture into whatever the upstream uses. Packages built from source point at their own archives instead. See Artifacts and platforms.

What happens on install

install:
  - copy: {src: "{{.Artifact}}", dst: "bin/jq", mode: 0o755}
bins: ["bin"]

Each version installs into its own directory under NEM_HOME, and the actions say how the downloaded file ends up there. bins lists the directories that join PATH; bin is the default, so the line above could be left out. See Install actions.

What the package needs and gives

deps:
  - name: libgpg-error
    kind: link
    compat: "1"
env:
  - name: JAVA_HOME
    value: "{{.InstallDir}}"

Neither appears in the jq manifest because jq needs nothing and exports nothing. deps pulls other packages in alongside this one; env puts values in the environment of every project that uses it; libs marks a package as a library others can link against. See Dependencies and exports.

The versions

versions:
  - version: 1.8.2
    sha256:
      darwin/arm64: "2d75…"
      darwin/amd64: "e94b…"
      linux/arm64: "8b85…"
      linux/amd64: "b1c2…"

Every version that can be installed, newest first, with a checksum per platform. A nem use without a version takes the first entry, and lint rejects a list that is out of order. nem catalog bump writes these entries so you rarely type a checksum yourself.

When build and test appear

build replaces the download with a recipe: where the source is, what to run, and what directory the result lands in. test is a list of shell commands that prove an installed version works. Both are optional and have their own guides, Building from source and Testing packages.

Manifests are strict: a key nem does not know fails lint instead of being ignored. nem catalog fmt rewrites a manifest in a stable layout and keeps your comments, so formatting never becomes a review topic.

Quickstart Version discovery