Valider la compilation Apple Silicon d’un module Node.js natif sur un Mac cloud

Le fait qu’un module Node.js natif se charge correctement sur une machine de développement ne garantit pas qu’il puisse être livré de manière fiable sur un Mac cloud Apple Silicon. Des fichiers précompilés issus du cache, des artefacts de compilation absents du paquet publié ou des chemins de bibliothèques dynamiques incorrects peuvent donner l’impression que npm install a réussi, alors que le premier appel à require() échoue sur une machine propre. Une approche plus fiable consiste à réunir la reconstruction depuis les sources, l’inspection des binaires, le contrôle du paquet et l’installation isolée dans une même chaîne de validation.

Fixer d’abord l’environnement de référence

Avant de commencer, consignez l’environnement d’exécution au lieu de vider immédiatement les caches et de tout réinstaller. Un module Node.js natif peut utiliser N-API ou dépendre d’une ABI de module précise ; leurs limites de compatibilité ne sont pas les mêmes. Le projet doit fixer la version majeure de Node.js au moyen de .nvmrc, de .node-version ou de paramètres CI, et inscrire également la version de npm dans les journaux.

uname -m
sw_vers
node --version
npm --version
node -p "process.versions.napi || 'no-napi'"
node -p "process.versions.modules"
xcode-select -p
clang --version

Dans un environnement Apple Silicon, uname -m doit renvoyer arm64. Si le processus du terminal s’exécute lui-même sous une autre architecture, les résultats de compilation obtenus ensuite ne seront pas représentatifs de l’environnement cible. Vérifiez aussi que xcode-select -p pointe vers la chaîne d’outils attendue, afin d’éviter qu’une mise à jour du système ne change discrètement les outils en ligne de commande utilisés.

La validation ne consiste pas à vérifier si « le répertoire actuel fonctionne », mais à déterminer si les sources du dépôt permettent de produire un artefact conforme à l’architecture cible et chargeable depuis le paquet final destiné à la publication.

Forcer une reconstruction depuis les sources dans un espace de travail propre

N’effectuez pas la validation d’une version dans un répertoire de travail utilisé au quotidien. Commencez par extraire un commit déterminé, puis supprimez le répertoire des dépendances et le répertoire de compilation propre au module. Si le projet génère ses fichiers .node au moyen de scripts d’installation, conservez l’intégralité des journaux d’installation.

git status --short
git rev-parse HEAD
rm -rf node_modules build
npm cache verify
npm ci
npm rebuild --build-from-source

npm cache verify contrôle uniquement la structure du cache ; cette commande ne prouve pas que la compilation n’a pas utilisé de données mises en cache. L’étape essentielle reste donc --build-from-source. Si le projet dispose d’un script de compilation explicite, exécutez ensuite npm run build au lieu de supposer que npm rebuild couvre toutes les étapes de génération.

En cas d’échec, conservez d’abord la sortie complète, puis vérifiez Python, le compilateur, les chemins du SDK et les fichiers d’en-tête. Ne supprimez pas tous les caches à la première erreur. Un nettoyage indifférencié détruit les éléments utiles au diagnostic et empêche de déterminer si le problème provient de la chaîne d’outils, du code source ou du script d’installation.

Distinguer N-API de l’ABI des modules

Pour un module utilisant N-API, consignez la version minimale de N-API déclarée et effectuez un test de chargement avec la version cible de Node.js. Les extensions qui dépendent directement de l’ABI des modules doivent généralement être compilées séparément pour chaque version majeure de Node.js. Un binaire produit pour une version ne doit pas être copié puis réutilisé avec une autre.

Inspecter l’architecture Mach-O et les dépendances dynamiques

Une fois la compilation terminée, recherchez tous les binaires natifs au lieu de contrôler uniquement le premier fichier présent dans le chemin habituel.

find . -type f -name '*.node' -not -path './node_modules/.cache/*' -print0 |
  xargs -0 file

find . -type f -name '*.node' -not -path './node_modules/.cache/*' -print0 |
  while IFS= read -r -d '' binary; do
    echo "== $binary"
    lipo -info "$binary"
    otool -L "$binary"
  done

Lorsque la cible est Apple Silicon, chaque fichier .node destiné à être livré doit contenir arm64. Un binaire universel n’est nécessaire que si le périmètre de publication couvre explicitement les deux architectures. Ne fusionnez pas, pour la forme, deux tranches qui n’ont pas fait l’objet de tests équivalents.

L’examen de otool -L doit surtout permettre de repérer les chemins absolus propres à la machine de développement, les répertoires temporaires et les bibliothèques dynamiques personnalisées qui ne sont pas livrées avec le paquet. Les chemins des frameworks système peuvent généralement être conservés, mais toute référence à un répertoire personnel ou à l’espace de travail de compilation doit être corrigée avant la publication. Si le module fournit des fichiers .dylib, vérifiez aussi qu’ils figurent bien dans la liste des fichiers empaquetés et qu’ils utilisent des chemins de chargement portables.

Valider le véritable paquet npm destiné à la publication

Tester directement dans le répertoire des sources permet à des fichiers non déclarés, à des chemins relatifs et à des artefacts résiduels de participer au chargement. Avant la publication, générez un tarball, puis installez-le dans un répertoire vide.

rm -rf .package-check
mkdir .package-check

npm pack --json > .package-check/pack.json
PACKAGE_FILE="$(node -e "
const fs=require('fs');
const data=JSON.parse(fs.readFileSync('.package-check/pack.json','utf8'));
process.stdout.write(data[0].filename);
")"

tar -tzf "$PACKAGE_FILE"
cd .package-check
npm init -y >/dev/null
npm install "../$PACKAGE_FILE"
node -e "const addon=require('your-module'); console.log(typeof addon)"

Remplacez your-module par le véritable nom du paquet et complétez la dernière ligne pour effectuer un appel métier minimal. Le test de bon fonctionnement doit déclencher au moins une fonction native, et pas seulement vérifier la présence du point d’entrée JavaScript. Si le module propose des interfaces synchrones et asynchrones, exécutez chacune d’elles une fois et contrôlez le code de sortie du processus.

Examinez également la sortie de tar -tzf : la licence, les déclarations de types, le point d’entrée JavaScript, le fichier .node cible et les bibliothèques dynamiques nécessaires doivent être présents. En revanche, les caches de sources, les identifiants de test, les journaux temporaires et les configurations locales ne doivent pas entrer dans le paquet.

Transformer les pannes courantes en barrières de publication

Il est recommandé de décomposer la validation en conditions d’échec indépendantes, afin qu’un vague « échec de compilation » ne masque pas la cause réelle :

1. Barrière d’environnement : arrêter le processus si l’architecture de la machine, Node.js, npm, N-API ou l’ABI ne correspondent pas aux valeurs déclarées.
2. Barrière de reconstruction : après la suppression des artefacts existants, la compilation depuis les sources doit réussir et produire un nouveau fichier .node.
3. Barrière d’architecture : chaque binaire livré doit contenir la tranche arm64 cible.
4. Barrière des dépendances : aucune référence à l’espace de travail, à un répertoire personnel ou à une bibliothèque dynamique absente du paquet n’est autorisée.
5. Barrière du contenu du paquet : le résultat de npm pack fait foi, et non le contenu du répertoire des sources.
6. Barrière d’exécution : installer le tarball dans un répertoire isolé et appeler au moins une API native.

Lors de l’exécution de cette procédure sur DPLYMAC, la description de l’environnement de chaque tâche, le hash du commit, la somme de contrôle du tarball et la sortie du test de bon fonctionnement peuvent être conservés ensemble comme preuve de compilation. Ainsi, même après une mise à niveau de Node.js ou des outils de compilation, il reste possible de déterminer si une différence est apparue au niveau de l’environnement, de la compilation, de l’empaquetage ou de l’exécution.

Les critères de livraison finaux doivent rester simples : une extraction propre peut être reconstruite, l’architecture du binaire est correcte, les dépendances dynamiques sont portables, le contenu du paquet publié est complet et ce paquet réussit un appel réel dans un environnement isolé. Ce n’est qu’une fois ces cinq conditions remplies que le module natif peut être considéré comme validé pour Apple Silicon.

Questions fréquentes