Provided by: pkg-js-tools_0.14.36_all 
NAME
pkg-js-tools - collection of tools to aid packaging Node modules in Debian.
[[_TOC_]]
WORKING WITH SALSA.DEBIAN.ORG REPOSITORY
To use salsa(1) with pkg-javascript configuration, add something like that in your
.bashrc:
alias js-salsa='salsa --conf-file +/usr/share/pkg-js-tools/pkg-js-salsa.conf'
Then you can use salsa simply. Some examples:
• if you created a local repo and want to create and push it on
https://salsa.debian.org/js-team, launch simply:
js-salsa push_repo .
• to configure a repo already pushed:
js-salsa update_safe node-foobar
• to clone locally a js-team package:
js-salsa co node-foobar
See salsa(1) for more.
DEBHELPER ADDON
pkg-js-tools debhelper addon is automatically loaded if a package build-depends on
dh-sequence-nodejs or (old fashion) if dh is called with --with nodejs in debian/rules.
Quick use
Examples of basic migration to pkg-js-tools: Switch test and install to pkg-js-tools
https://salsa.debian.org/js-team/node-static-module/-/commit/2c6d9fb1
How it works
pkg-js-tools provides hooks for these steps:
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│ Step Comment │
├─────────────────────────────────────────────────────────────────────────────────────────┤
│ configure populate node_modules/ │
│ build build components and main module │
│ test test components and main module │
│ install install components and main │
│ module │
│ installdocs can auto-generate docs for each │
│ component │
│ clean clean pkg-js-tools stuff │
└─────────────────────────────────────────────────────────────────────────────────────────┘
Technically, it adds --buildsystem=nodejs to the corresponding dh_auto_<step> command.
Important note. Here:
• component is the directory name of a submodule (uscan(1) component or additional
components listed in debian/nodejs/additional_components). Example: types-glob
• module is the npmjs name. Example: @types/glob
See Group Sources Tutorial https://wiki.debian.org/Javascript/GroupSourcesTutorial for
more about embedding components.
Details:
• dh_auto_clean, cleans files automatically installed by pkg-js-tools itself
• dh_auto_configure, automatically populates node_modules directory:
• links embedded components
• links global modules listed in debian/nodejs/extlinks
• copies global modules listed in debian/nodejs/extcopies
• dh_auto_build, Remember to add a dh_auto_build --buildsystem=nodejs in
override_dh_auto_build section if your debian/rules file has such section, else this
step will be ignored. Builds:
• components by launching sh -ex debian/nodejs/<component-name>/build in this file
exists
• main module by launching sh -ex debian/nodejs/build if exists
• dh_auto_test, tests:
• components by launching sh -ex debian/nodejs/<component-name>/test if this file exists
• main module by launching sh -ex debian/tests/pkg-js/test if this file exists. This
test is also used by pkg-js-autopkgtest(7) during autopkgtest. If you want to have a
different test during build, set this test in debian/nodejs/test.
• dh_auto_install: installs modules in the good directories and provides some debhelper
variables to be used in debian/control. Note that if your package provides more that one
binary package, you have to use some debian/<package-name>.install files to distribute
the files. Steps:
• components: determine files to install using the same algorithm than main module and
install them:
• nowhere if component if debian/nodejs/submodules exists and component isn't listed
in it (an empty debian/nodejs/submodules drops all components)
• nowhere if component is listed in debian/nodejs/additional_components with a "!"
prefix
• in main nodejs directories if component is listed in debian/nodejs/root_modules
• else: in a node_modules subdirectory of main module
• main module, determine files to install (see below) and install them in the "good"
directory:
• if "architecture" is "all": /usr/share/nodejs
• else: /usr/lib/${DEB_HOST_MULTIARCH}/nodejs
• links: builds symlinks listed in debian/nodejs/links. Same usage as debian/links
except that source or destination not starting with / are related to arch path
(/usr/share/nodejs or /usr/lib/<gnu-arch>/nodejs)
• Build pkgjs-lock.json files: if package "maybe a bundle" (built with webpack,
browserify,...), pkg-js-tools builds a pkgjs-lock.json for each module. This files may
help in Debian transitions
• Variables usable in debian/control:
• ${nodejs:Version}: the version of nodejs used during build
• ${nodejs:Provides}: virtual names to be added into "Provides:" field. This lists
all modules installed in nodejs root directories
• ${nodeFoo:Provides}: for a source package that provides several binary packages,
dh-sequence-nodejs filters ${nodejs:Provides} for each binary package. The package
name is converted into its camelcase name: node-jest-worker becomes nodeJestWorker
• ${nodejs:BuiltUsing}: when package "maybe a bundle", lists packages and versions
used to build package. Use it in X-Javascript-Built-Using field
• dh_installdocs: dh-sequence-nodejs provides a tool named dh_nodejs_autodocs which can be
used in a override_dh_installdocs to automatically generate documentation for each
component. See related manpage
Automatically detect some additional components
Starting from 0.12.0, dh-sequence-nodejs automatically reads lerna.conf and reads
"packages" field to find additional components.
Starting from 0.12.7, it does the same when package.json has a "workspaces" field.
This auto-detection automatically drops "test" and "tests" directories. You can override
this behavior using debian/additional_components.
If a component should not be considered, insert its name preceded by a "!" in
debian/nodejs/additional_components.
To disable this feature, use dh-sequence-nodejs-no-lerna.
Algorithm to determine files to install
pkg-js-tools tries to reproduce npm(1) behavior: it reads package.json and/or .npmignore
files to determine files to install except that it drops licenses, *.md, doc*, example*,
test*, makefiles,...`.
This behavior is overridden if:
• debian/nodejs/install (or `debian/nodejs/<component-name>/install) exists. This file
uses the same format than debian/install.
• debian/nodejs/files (or `debian/nodejs/<component-name>/files) exists. the content of
this file replaces "files" entry of package.json
pkg-js-tools files
• all steps:
• debian/nodejs/additional_components is used to set some subdirectories that should be
considered as components even if they are not listed in debian/watch. Content example:
packages/*. Important note: in this example, component name is packages/foo in every
other files, including paths
• debian/nodejs/main is used to indicates where is the main module. In a package
containing only components (bundle package), you should choose one of them as main
component
• configure step:
• debian/build_modules additional modules needed to build, will be linked in
node_modules directory
• debian/nodejs/component_links lists needed links between components: links
../../component-src in component-dst/node_modules/component-src-name
• debian/nodejs/<component-name>/nolink avoids node_modules links creation for this
component (configuration step)
• debian/nodejs/extlinks lists installed node modules that should be linked into
node_modules directory (modules are searched using nodejs algorithm). You can mark
them with "test" to avoid errors when build profile contains nocheck
• debian/nodejs/extcopies lists installed node modules that should be copied into
node_modules directory. You can also mark them with "test"
• debian/nodejs/<component>/extlinks lists installed node modules that should be linked
in <component>/node_modules directory (test flag available)
• debian/nodejs/<component>/extcopies lists installed node modules that should be copied
in <component>/node_modules directory (test flag available)
• build step:
• debian/nodejs/build custom build. An empty file stops auto build
• debian/nodejs/<component>/build: same for components
• debian/nodejs/build_order orders components build (one component per line). Else
components are built in alphabetic order except components declared in
debian/nodejs/component_links: a component that depends on another is built after
• test step:
• debian/tests/test_modules: additional modules needed for test, will be linked in
node_modules directory during test step only
• debian/tests/pkg-js/test: script to launch during test (launched with set -e)
• debian/tests/pkg-js/files: lists other files than debian/tests/test\_modules/\* and
installed files needed for autopkgtest (default: test*)
• debian/nodejs/test: overwrite debian/tests/pkg-js/test during build if test differs in
build and autopkgtest
• debian/nodejs/<component-name>/test: same for components (launched during build only)
• autopkgtest files:
• debian/tests/autopkgtest-pkg-nodejs.conf: autodep8 configuration file which can be
used to add packages or restrictions during autopkgtest only
• extra_depends=p1, p2, p3 permits one to add p1, p2 and p3 packages
• extra-restrictions=needs-internet permits one to add additional restrictions
during autopkgtest
• debian/tests/pkg-js/require-name: contains the name to use in autopkgtest require
test instead of package.json value
• install step:
• debian/nodejs/submodules lists components to install (all if missing)
• debian/nodejs/root_modules lists components to install in nodejs root directory
(instead of node_modules subdirectory). If this file contains *, all components are
installed in root directory
• debian/nodejs/files overwrites package.json#files field.
• debian/nodejs/<component-name>/files overwrites package.json#files field. An empty
file avoid any install
• debian/nodejs/name overwrites package.json#name field.
• debian/nodejs/<component-name>/name overwrites package.json#name
• debian/nodejs/install overwrites debian/nodejs/files: same usage as debian/install
except that destination not starting with / are related to arch path
(/usr/share/nodejs or /usr/lib/<gnu-arch>/nodejs)
• debian/nodejs/<component-name>/install same as debian/nodejs/install for components
• link step:
• debian/nodejs/links: same usage as debian/links except that source or destination not
starting with / are related to arch path (/usr/share/nodejs or
/usr/lib/<gnu-arch>/nodejs)
To install a component in another directory, set its files in debian/install.
Example:
• debian/control
...
Testsuite: autopkgtest-pkg-nodejs
Build-Depends: dh-sequence-nodejs
...
• debian/tests/pkg-js/test
mocha -R spec
See also pkg-js-autopkgtest README ../autopkgtest/README.md.
Multiple binary packages
When debian/control provides more than one binary package, dh_auto_install populates a
debian/tmp and dh_install install files in each package. In this case, you must write a
debian/<package>.install for each binary package. Each line with only one argument is
related to debian/tmp. Examples:
• debian/node-arch-indep.install: pick files from debian/tmp
usr/share/nodejs/foo/
• debian/node-arch-dep.install: pick files from debian/tmp
usr/lib/*/nodejs/foo/
• debian/libjs.install: pick files from sources
dist/* usr/share/javascript/foo/
Links
Since path is not fixed for arch-dependent package, you must write debian/nodejs/links:
# debian/nodejs/links
foo/bin/cli.js /usr/bin/foo
With a arch independent package, pkg-js-tools transforms this into:
/usr/share/nodejs/foo/bin/cli.js /usr/bin/foo
and for a arch dependent package, it uses DEB_GNU_ARCH. Example with amd64:
/usr/lib/x86_64-linux-gnu/foo/bin/cli.js /usr/bin/foo
All fields that does not start with / are prefixed with the good nodejs path
Component docs
Starting from version 0.13.0, pkg-js-tools provides dh_nodejs_autodocs. This tool
automatically install README.md, CONTRIBUTING.md,... for each root component in its
/usr/share/doc/node-<name> directory. And if no debian/*docs is found, it does the same
for the main component. To use it:
override_dh_installdocs:
dh_installdocs
dh_nodejs_autodocs
.eslint* files
pkg-js-tools auto installer always removes .eslint* files unless it is explicitly
specified in debian/nodejs/**/files or debian/nodejs/**/install.
Having different test between build and autopkgtest
When debian/nodejs/test exists, this file is used during build test instead of
debian/tests/pkg-js/test. This permits one to have a different test. You can also
overwrite dh_auto_test step in debian/rules:
override_dh_auto_test:
# No test during build (test needs Internet)
Autopkgtest additional test packages or test restrictions
autodep8 allows one to add additional packages during autopkgtest (and/or additional
restrictions) by using a debian/tests/autopkgtest-pkg-nodejs.conf file:
extra_depends=mocha, npm
extra-restrictions=needs-internet
LINTIAN PROFILES
pkg-js-tools provides a lintian profile:
• pkg-js-extra: launches additional checks (repo consistency see debcheck-node-repo below)
To use them:
lintian --profile pkg-js-extra ../node-foo_1.2.3-1.changes
OTHER TOOLS
See related manpages.
• add-node-component: automatically modifies gbp.conf and debian/watch to add a node
component. See JS Group Sources Tutorial
https://wiki.debian.org/Javascript/GroupSourcesTutorial. It can also list components or
modules (real names)
• getFromNpmCache: export npm cache content to standard output
• github-debian-upstream: launches it in source repo to create a debian/upstream/metadata
(works only if upstream repo is on GitHub)
• nodepath: shows the path of a node module (npm name). You can use -p to show also the
Debian package. Option -o shows only Debian package name.
• debcheck-node-repo: checks repo consistency: compares vcs repo registered in npm
registry with the source repo declared in debian/watch"
• dh_nodejs_autodocs: automatically select and install documentation files toinstall for
each component
• mjs2cjs: build commonjs file using rollup
• pkgjs-audit: creates a temporary package-lock.json file using Debian package values used
by the module to analyze, and launch a npm audit. If module is a bundle (and then has a
pkgjs-lock.json), pkgjs-audit uses pkgjs-lock.json, else it generates its
package-lock.json using available values
• pkgjs-depends: search recursively dependencies of the given module name (if not given,
use current package.json) and displays related Debian packages and missing dependencies
• pkgjs-install: same as npm install but uses Debian JS modules when available
• pkgjs-install-minimal: same as pkgjs-install but uses only available Debian modules. It
is included in dh-nodejs so can be used during build
• pkgjs-ls: same as npm ls but it search also in global nodejs paths
• pkgjs-run: same as npm run
• pkgjs-utils, pkgjs-ln, pkgjs-main, pkgjs-pjson: various utilities. See pkgjs-utils(1)
manpage.
SEE ALSO
debhelper(7), pkg-js-autopkgtest(7), uscan(1), add-node-component(1),
github-debian-upstream(1), nodepath(1), mjs2cjs(1), pkgjs-ls(1), pkgjs-depends(1),
pkgjs-audit(1), pkgjs-utils(1), pkgjs-install(1)
FEATURES HISTORY
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│ TOOL Minimal version │
├─────────────────────────────────────────────────────────────────────────────────────────┤
│ add-node-component 0.8.14 │
│ add-node-component --cmp-tree 0.9.22 │
│ debcheck-node-repo 0.8.14 │
│ dh_nodejs_autodocs 0.13.0 │
│ dh_nodejs_autodocs auto_dispatch 0.14.5 │
│ dh_nodejs_substvars 0.14.5 │
│ dh-make-node 0.9.18 │
│ getFromNpmCache 0.14.32 │
│ mjs2cjs 0.12.3 │
│ mjs2cjs -a 0.14.14 │
│ pkgjs-audit 0.11.2 │
│ pkgjs-depends 0.9.54 │
│ pkgjs-depends --graph 0.14.34 │
│ pkgjs-install 0.14.20 │
│ pkgjs-install-minimal 0.14.27 │
│ pkgjs-ln 0.9.76 │
│ pkgjs-ls 0.9.30 │
│ pkgjs-main 0.9.76 │
│ pkgjs-pjson 0.9.76 │
│ pkgjs-run 0.14.22 │
│ pkgjs-utils 0.9.75 │
└─────────────────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│ FEATURE Minimal version │
├─────────────────────────────────────────────────────────────────────────────────────────┤
│ additional_components 0.9.11 │
│ auto build (grunt) 0.9.3 │
│ autopkgtest skip 0.9.30 │
│ auto-install (arch-dep) 0.9.27 │
│ build order 0.9.10 │
│ dh-sequence-nodejs 0.9.41 │
│ follow lerna.json#useWorkspaces 0.14.8 │
│ .npmignore support 0.9.53 │
│ support lerna.conf 0.12.0 │
│ support workspaces 0.12.7 │
│ debian/nodejs/main 0.9.11 │
│ debian/tests/test_modules 0.9.33 │
│ debian/build_modules 0.9.33 │
│ ${nodejs:BuiltUsing} 0.11.8 │
│ ${nodejs:Provides} 0.9.10 │
│ ${nodejs:Version} 0.9.38 │
│ ${nodeFoo:Provides} 0.14.5 │
└─────────────────────────────────────────────────────────────────────────────────────────┘
COPYRIGHT AND LICENSE
Copyright Yadd <yadd@debian.org>
This library is free software; you can redistribute it and/or modify it under the terms of
the GNU General Public License as published by the Free Software Foundation; either
version 2, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details.
On Debian systems, the complete text of version 2 of the GNU General Public License can be
found in `/usr/share/common-licenses/GPL-2'. If not, see GNU licenses
http://www.gnu.org/licenses/;
August 2022 PKG-JS-TOOLS()