Man page - pkg-js-tools(7)
Packages contains this manual
Manual
PKG-JS-TOOLS
NAMEWORKING WITH SALSA.DEBIAN.ORG REPOSITORY
DEBHELPER ADDON
Quick use
How it works
Automatically detect some additional components
Algorithm to determine files to install
pkg-js-tools files
Multiple binary packages
Links
Component docs
.eslint* files
Having different test between build and autopkgtest
Autopkgtest additional test packages or test restrictions
LINTIAN PROFILES
OTHER TOOLS
SEE ALSO
FEATURES HISTORY
COPYRIGHT AND LICENSE
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 , 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
How it works
pkg-js-tools provides hooks for these steps:
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 |
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 .
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
.
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
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
;