Un fichier module.json est requis pour chaque module externe de Nelson ; il permet de le gérer facilement avec la fonction nmm.

module: identifiant unique (nom court du module, caractères alphanumériques), exemple : "module_skeleton_basic"

title: nom complet du module (nom convivial), exemple : "Module skeleton basic"

summary: description sur une ligne, exemple : "Skeleton of a basic nelson package"

version: numéro de version en utilisant le versionnement sémantique, exemple : "1.0.0"

platforms: plateformes supportées.

"all" pour toutes les plateformes

autres plateformes :

"win32" : Windows 32 bits

"win64" : Windows 64 bits

"maci64" : macOS 64 bits

"maca64" : macOS Apple silicon

"maci32" : macOS 32 bits

"glnxa64" : Linux 64 bits

"glnxa32" : Linux 32 bits

exemple :["win64", "glnxa64"], le module ne sera disponible que sur Windows et Linux 64 bits.

L'architecture courante doit correspondre exactement à l'une des plateformes listées, sauf si all est présent.

nelson: versions de Nelson supportées, exemple : " <2.0.0" (par défaut)

builtin: true si le module nécessite un compilateur C/C++, false si le module contient uniquement des macros.

author: informations sur l'auteur : nom, email et site web

Exemple :

{

"name": "Allan CORNET",

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

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

}

homepage: page d'accueil du module, exemple "https://github.com/nelson-lang/module_skeleton_basic"

issues: URL optionnelle du gestionnaire de tickets du module, exemple "https://github.com/nelson-lang/module_skeleton_basic/issues"

documentation: URL optionnelle de la documentation du module, exemple "https://nelson-lang.github.io/nelson-website/"

description: description complète du module, format Markdown supporté, exemple : "nelson's module skeleton (macros only)"

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

license: expression de licence SPDX sous laquelle la boîte à outils sera publiée, exemple : "BSD-3-Clause", "MIT" ou "LGPL-3.0-or-later OR GPL-3.0-or-later".

keywords: mots-clés décrivant votre module.

Exemple :

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

dependencies: liste des dépendances de modules {} (par défaut) ou paires nom : url

{

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

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

}

Lors de la création d'un paquet, les versions installées des dépendances sont résolues dans module-lock.json. Le fichier de verrou enregistre aussi sa version de format, le type de paquet (source ou binary), les métadonnées de source, la version de Nelson, l'architecture, le tag ABI et les checksums des fichiers installés essentiels. Une archive .nmz ne peut être installée que si ces dépendances verrouillées sont déjà installées. Les paquets binaires exigent aussi que l'architecture Nelson et le tag ABI verrouillés correspondent au build Nelson en cours.

Lors de l'installation d'un module source, les valeurs de dépendances peuvent être des chemins locaux, des archives .nmz, des dépôts Git HTTP, des versions exactes ou des contraintes semver. Les dépendances source sont installées récursivement avant la construction du module. Si l'arborescence source contient déjà module-lock.json, ses versions exactes de dépendances sont utilisées pour une installation reproductible. Les installations source construisent et exécutent les tests dans un répertoire temporaire de staging avant que le module soit écrit dans son emplacement final. Une installation source en échec conserve intacte toute version précédente déjà installée du même module.

Une archive .nmz peut être accompagnée d'un fichier checksum .sha256. nmm vérifie ce checksum lorsqu'il est présent, sinon il vérifie après extraction les checksums de fichiers embarqués dans module-lock.json.

nmm('validate', module_path) vérifie que ces champs obligatoires sont présents et correctement formés avant installation ou empaquetage.

nmm('validate', module_path, '-strict') ajoute des vérifications orientées publication pour repository, homepage, des keywords non vides, au moins un fichier de test et au moins un fichier d'aide XML.

En mode strict, repository et homepage doivent être des URLs HTTP ou HTTPS. Les champs optionnels issues et documentation ne sont validés que lorsqu'ils sont présents et doivent alors être des URLs HTTP ou HTTPS. nmm('validate', module_path, '-json') retourne un rapport de validation exploitable par des outils.

La validation vérifie aussi la structure du paquet : un module source doit inclure builder.m ou loader.m, etc/startup.m, etc/finish.m, help et tests. L'empaquetage exige au moins un fichier de test et exécute les tests du paquet avant d'écrire une archive.

nmm('pack', module_path, destination_dir) utilise ce descripteur pour construire un module source et créer une archive de paquet reproductible avec fichier de verrou et checksum.

nmm('lock', module_path) écrit ou rafraîchit module-lock.json pour un module source sans l'installer ni l'empaqueter.

nmm('publish', package_filename) lit le fichier de verrou du paquet et module.json, puis écrit une entrée de registre local contenant les métadonnées du paquet, le chemin source du paquet et son checksum SHA-256. La commande écrit aussi un sidecar registry.json.sha256. Lorsque NELSON_NMM_REGISTRY_SIGNING_KEY est défini, elle écrit et vérifie aussi un sidecar à clé registry.json.sig. Les installations d'archives depuis le registre vérifient le checksum du paquet et les fichiers de registre locaux exigent le sidecar de checksum.

Un index de registre est un document JSON avec un tableau packages. Chaque entrée de paquet contient les métadonnées comme le nom, la version, le type de paquet, les plateformes, la compatibilité Nelson, les dépendances, le checksum et une métadonnée de signature de paquet optionnelle. Une entrée installable contient aussi source, url ou archive. Les dépendances déclarées par une entrée installable sont résolues récursivement avant l'installation de la source du paquet. nmm('search'), nmm('info') et nmm('versions') lisent cet index.

Les versions du registre sont aussi utilisées par nmm('outdated') et nmm('update'). Les archives .nmz vérifiées sont mises en cache localement et peuvent être réutilisées par les installations offline.

Plusieurs versions du même module peuvent être installées côte à côte. modules.json stocke la version active dans les champs racine path et version, toutes les versions installées dans versions, et la version par défaut explicite dans pinned_version lorsque nmm('pin') est utilisé.