Scroll to navigation

PKG-JS-TOOLS(1) General Commands Manual PKG-JS-TOOLS(1)

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-teamlaunch 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

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 .br additional components listed in \fBdebian/nodejs/additional_components\fP).
    Example: types-glob
  • module is the npmjs name. Example: @types/glob

See Group Sources Tutorial

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 \fBdebian/nodejs/submodules\fP drops all .br 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
    (\fB/usr/share/nodejs\fP or \fB/usr/lib/<gnu\-arch>/nodejs\fP)
  • Build \fBpkgjs\-lock\.json\fP 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 &quot;files&quot; 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 .br 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 (\fBtest\fP flag available)
  • debian/nodejs/<component>/extcopies lists installed node modules that
    should be copied in <component>/node_modules directory (\fBtest\fP 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 \fBset \-e\fP)
  • debian/tests/pkg\-js/files: lists other files than
    debian/tests/test\_modules/\* and installed files needed for autopkgtest
    (default: \fBtest*\fP)
  • 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 \fBnode_modules\fP 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 (\fB/usr/share/nodejs\fP or \fB/usr/lib/<gnu\-arch>/nodejs\fP)
  • 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
(\fB/usr/share/nodejs\fP or \fB/usr/lib/<gnu\-arch>/nodejs\fP)

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.

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/

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 .br 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.

    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 \fBpkgjs\-lock\.json\fP), 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_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-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;

November 2022