A module.json file is required for each Nelson external module and is used by the nmm function to manage the module.

module: unique identifier module short name (alphanumeric characters), example: "module_skeleton_basic"

title: complete module name (human friendly name), example: "Module skeleton basic"

summary: one line description, example: "Skeleton of a basic nelson package"

version: version number using semantic versioning, example: "1.0.0"

platforms: platforms supported.

"all" for all platforms

others platforms:

"win32": windows 32 bits

"win64": windows 64 bits

"maci64": macos 64 bits build

"maca64": macos Apple silicon build

"maci32": macos 32 bits build

"glnxa64": linux 64 bits build

"glnxa32": linux 64 bits build

example: ["win64", "glnxa64"], module will be available only on windows and linux 64 bits platforms.

The current architecture must match one listed platform exactly, unless all is listed.

nelson: nelson's supported versions, example: " <2.0.0" (default)

builtin: true if module requires C/C++ compiler, false if module have only macros.

author: Author information: name, email and website

Example:

{

"name": "Allan CORNET",

"email": "nelson.numerical.computation@gmail.com",

"url": "https://nelson-lang.github.io/nelson-website/"

}

homepage: homepage of the module, example "https://github.com/nelson-lang/module_skeleton_basic"

issues: optional issue-tracker URL of the module, example "https://github.com/nelson-lang/module_skeleton_basic/issues"

documentation: optional documentation URL of the module, example "https://nelson-lang.github.io/nelson-website/"

description: full description of the module, markdown format supported, example: "nelson's module skeleton (macros only)"

copyright copyright description, example: "Copyright © 2019-present Allan CORNET"

license: SPDX license expression under which the toolbox will be published, example: "BSD-3-Clause", "MIT" or "LGPL-3.0-or-later OR GPL-3.0-or-later".

keywords: keywords describing your module.

Example:

["interpreter", "scientific-computing", "programming-language", "matrix-functions", "skeleton"]

dependencies: list of modules dependencies {} (default) or name : url values

{

"module_a": "https://module_a.git#v1.0.0",

"module_b": "https://module_b.git#v1.0.0"

}

During package creation, installed dependency versions are resolved into module-lock.json. The lock file also records its format version, package type (source or binary), source metadata, Nelson version, architecture, ABI tag and checksums for key installed files. A packaged .nmz archive can be installed only when these locked dependencies are already installed. Binary packages also require the locked Nelson architecture and ABI tag to match the running Nelson build.

When installing a source module, dependency values can be local paths, .nmz archives, HTTP Git repositories, exact versions or semver constraints. Source dependencies are installed recursively before the module is built. If the source tree already contains module-lock.json, its exact dependency versions are used for a reproducible install. Source installs build and run tests in a temporary staging directory before the module is committed to the final install location. A failed source install keeps any previous installed version of the same module intact.

A .nmz archive can be accompanied by a .sha256 checksum file. nmm verifies this checksum when it is present, and otherwise verifies the file checksums embedded in module-lock.json after extraction.

nmm('validate', module_path) checks that these required fields are present and well formed before installation or packaging.

nmm('validate', module_path, '-strict') adds publish-oriented checks for repository, homepage, non-empty keywords, at least one test file and at least one XML help file.

In strict mode, repository and homepage must be HTTP or HTTPS URLs. The optional issues and documentation fields are validated only when present and must then be HTTP or HTTPS URLs. nmm('validate', module_path, '-json') returns a machine-readable validation report.

Validation also checks the package layout: a source module must include builder.m or loader.m, etc/startup.m, etc/finish.m, help, and tests. Packaging requires at least one test file and runs the package tests before writing an archive.

nmm('pack', module_path, destination_dir) uses this descriptor to build a source module and create a reproducible package archive with a lock file and checksum.

nmm('lock', module_path) writes or refreshes module-lock.json for a source module without installing or packaging it.

nmm('publish', package_filename) reads the package lock file and module.json, then writes a local registry entry containing package metadata, the package source path and SHA-256 checksum. It also writes a registry.json.sha256 sidecar. When NELSON_NMM_REGISTRY_SIGNING_KEY is set, it writes and verifies a keyed registry.json.sig sidecar too. Registry archive installs verify the package checksum and local registry files require the checksum sidecar.

A registry index is a JSON document with a packages array. Each package entry contains package metadata such as name, version, package type, platforms, Nelson compatibility, dependencies, checksum and optional package signature metadata. An installable entry also contains source, url or archive. Dependencies declared by an installable entry are resolved recursively before the package source is installed. nmm('search'), nmm('info') and nmm('versions') read this index.

Registry versions are also used by nmm('outdated') and nmm('update'). Checked .nmz archives are cached locally and can be reused by offline installs.

Several versions of the same module can be installed side by side. modules.json stores the active version in the top-level path and version fields, stores all installed versions in versions, and stores an explicit default in pinned_version when nmm('pin') is used.