NAME
pkg-js-tools - collection of tools to aid packaging Node modules in Debian.
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
salsa ⟨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
XB-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
- •
-
dh_install: dh-sequence-nodejs provides a tool named
dh_nodejs_build_debug_package which can be used to build a separate
debug package with sourcemap files when package size is too big. 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 running tests can be
added to this directory as subdirectories, which 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)
NB: 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
- •
-
dh_nodejs_build_debug_package: move sourcemap files from binary
packages to a separated debug package
- •
-
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-lerna run: same as lerna run (only run command is implemented)
- •
-
pkgjs-utils, pkgjs-ln, pkgjs-main, pkgjs-pjson: various
utilities. See pkgjs-utils(1) manpage
- •
-
pkgjs: try to reproduce yarnpkg(1) commands with pkgjs-* scripts.
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_build_debug_package | 0.15.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 | 0.15.21 |
| 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-lerna | 0.15.13 |
| 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 |
| ordered_components_list | 0.15.13 |
| packages_list | 0.15.13 |
COPYRIGHT AND LICENSE
Copyright Yadd <[email protected]>
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/⟩;