.TH "PKG\-JS\-TOOLS" "" "October 2022" "" "" .SH "NAME" \fBpkg-js-tools\fR \- collection of tools to aid packaging Node modules in Debian\. .P [[_TOC_]] .SH WORKING WITH SALSA\.DEBIAN\.ORG REPOSITORY .P To use salsa(1) with pkg\-javascript configuration, add something like that in your \.bashrc: .P .RS 2 .nf alias js\-salsa='salsa \-\-conf\-file +/usr/share/pkg\-js\-tools/pkg\-js\-salsa\.conf' .fi .RE .P Then you can use salsa simply\. Some examples: .RS 0 .IP \(bu 2 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 \. .IP \(bu 2 to configure a repo already pushed: js\-salsa update_safe node\-foobar .IP \(bu 2 to clone locally a js\-team package: js\-salsa co node\-foobar .RE .P See salsa(1) for more\. .SH DEBHELPER ADDON .P \fBpkg\-js\-tools\fR debhelper addon is automatically loaded if a package build\-depends on \fBdh\-sequence\-nodejs\fR or \fI(old fashion)\fR if \fBdh\fP is called with \fB\-\-with nodejs\fR in \fBdebian/rules\fP\|\. .SS Quick use .P Examples of basic migration to pkg\-js\-tools: Switch test and install to pkg\-js\-tools \fIhttps://salsa\.debian\.org/js\-team/node\-static\-module/\-/commit/2c6d9fb1\fR .SS How it works .P pkg\-js\-tools provides hooks for these steps: .TS tab(|) expand nowarn box; l l. T{ Step T}|T{ Comment T} _ T{ \fBconfigure\fR T}|T{ populate \fBnode_modules/\fP T} T{ \fBbuild\fR T}|T{ build components and main module T} T{ \fBtest\fR T}|T{ test components and main module T} T{ \fBinstall\fR T}|T{ install components and main module T} T{ \fBinstalldocs\fR T}|T{ can auto\-generate docs for each component T} T{ \fBclean\fR T}|T{ clean pkg\-js\-tools stuff T} .TE .P Technically, it adds \fB\-\-buildsystem=nodejs\fP to the corresponding \fBdh_auto_\fP command\. .P \fBImportant note\fR\|\. Here: .RS 0 .IP \(bu 2 \fBcomponent\fR is the directory name of a submodule \fI(uscan(1) component or additional components listed in \fBdebian/nodejs/additional_components\fP)\fR\|\. Example: \fBtypes\-glob\fP .IP \(bu 2 \fBmodule\fR is the npmjs name\. Example: \fB@types/glob\fP .RE .P See Group Sources Tutorial \fIhttps://wiki\.debian\.org/Javascript/GroupSourcesTutorial\fR for more about embedding components\. .P Details: .RS 0 .IP \(bu 2 \fBdh_auto_clean\fR, cleans files automatically installed by \fBpkg\-js\-tools\fR itself .IP \(bu 2 \fBdh_auto_configure\fR, automatically populates \fBnode_modules\fP directory: .RS .IP \(bu 2 links embedded components .IP \(bu 2 links global modules listed in \fBdebian/nodejs/extlinks\fP .IP \(bu 2 copies global modules listed in \fBdebian/nodejs/extcopies\fP .RE .IP \(bu 2 \fBdh_auto_build\fR, Remember to add a \fBdh_auto_build \-\-buildsystem=nodejs\fP in \fBoverride_dh_auto_build\fR section if your \fBdebian/rules\fP file has such section, else this step will be ignored\. Builds: .RS .IP \(bu 2 components by launching \fBsh \-ex debian/nodejs//build\fP in this file exists .IP \(bu 2 main module by launching \fBsh \-ex debian/nodejs/build\fP if exists .RE .IP \(bu 2 \fBdh_auto_test\fR, tests: .RS .IP \(bu 2 components by launching \fBsh \-ex debian/nodejs//test\fP if this file exists .IP \(bu 2 main module by launching \fBsh \-ex debian/tests/pkg\-js/test\fP 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 \fBdebian/nodejs/test\fP\|\. .RE .IP \(bu 2 \fBdh_auto_install\fR: installs modules in the good directories and provides some debhelper variables to be used in \fBdebian/control\fP\|\. Note that if your package provides more that one binary package, you have to use some \fBdebian/\.install\fP files to distribute the files\. Steps: .RS .IP \(bu 2 \fBcomponents\fR: determine files to install using the same algorithm than main module and install them: .RS .IP \(bu 2 nowhere if component if \fBdebian/nodejs/submodules\fP exists and component isn't listed in it \fI(an empty \fBdebian/nodejs/submodules\fP drops all components)\fR .IP \(bu 2 nowhere if component is listed in \fBdebian/nodejs/additional_components\fP with a "!" prefix .IP \(bu 2 in main nodejs directories if component is listed in \fBdebian/nodejs/root_modules\fP .IP \(bu 2 else: in a \fBnode_modules\fP subdirectory of main module .RE .IP \(bu 2 \fBmain module\fR, determine files to install \fI(see below)\fR and install them in the "good" directory: .RS .IP \(bu 2 if "architecture" is "all": \fB/usr/share/nodejs\fP .IP \(bu 2 else: \fB/usr/lib/${DEB_HOST_MULTIARCH}/nodejs\fP .RE .IP \(bu 2 \fBlinks\fR: builds symlinks listed in \fBdebian/nodejs/links\fP\|\. Same usage as \fBdebian/links\fP except that source or destination not starting with \fB/\fP are related to arch path \fI(\fB/usr/share/nodejs\fP or \fB/usr/lib//nodejs\fP)\fR .IP \(bu 2 \fBBuild \fBpkgjs\-lock\.json\fP\fR files: if package "maybe a bundle" \fI(built with webpack, browserify,\.\.\.)\fR, pkg\-js\-tools builds a \fBpkgjs\-lock\.json\fP for each module\. This files may help in Debian transitions .IP \(bu 2 Variables usable in \fBdebian/control\fP: .RS .IP \(bu 2 \fB${nodejs:Version}\fP: the version of nodejs used during build .IP \(bu 2 \fB${nodejs:Provides}\fP: virtual names to be added into "Provides:" field\. This lists all modules installed in nodejs root directories .IP \(bu 2 \fB${nodeFoo:Provides}\fP: for a source package that provides several binary packages, \fBdh\-sequence\-nodejs\fR filters \fB${nodejs:Provides}\fP for each binary package\. The package name is converted into its camelcase name: \fBnode\-jest\-worker\fR becomes nodeJestWorker .IP \(bu 2 \fB${nodejs:BuiltUsing}\fP: when package "maybe a bundle", lists packages and versions used to build package\. Use it in \fBXB\-Javascript\-Built\-Using\fR field .RE .RE .IP \(bu 2 \fBdh_installdocs\fR: \fIdh\-sequence\-nodejs\fR provides a tool named \fBdh_nodejs_autodocs\fR which can be used in a \fBoverride_dh_installdocs\fP to automatically generate documentation for each component\. See related manpage .IP \(bu 2 \fBdh_install\fR: \fIdh\-sequence\-nodejs\fR provides a tool named \fBdh_nodejs_build_debug_package\fR which can be used to build a separate debug package with sourcemap files when package size is too big\. See related manpage .RE .SS Automatically detect some additional components .P Starting from 0\.12\.0, dh\-sequence\-nodejs automatically reads lerna\.conf and reads "packages" field to find additional components\. .P Starting from 0\.12\.7, it does the same when package\.json has a "workspaces" field\. .P This auto\-detection automatically drops "test" and "tests" directories\. You can override this behavior using \fBdebian/additional_components\fR\|\. .P If a component should not be considered, insert its name preceded by a "!" in \fBdebian/nodejs/additional_components\fR\|\. .P To disable this feature, use \fBdh\-sequence\-nodejs\-no\-lerna\fR\|\. .SS Algorithm to determine files to install .P \fBpkg\-js\-tools\fR tries to reproduce \fBnpm(1)\fR behavior: it reads \fBpackage\.json\fP and/or \fB\|\.npmignore\fP files to determine files to install except that it drops licenses, *\|\.md, doc*, example*, test*, makefiles,\.\.\.`\. .P This behavior is overridden if: .RS 0 .IP \(bu 2 \fBdebian/nodejs/install\fP \fI(or `debian/nodejs//install)\fR exists\. This file uses the same format than \fBdebian/install\fP\|\. .IP \(bu 2 \fBdebian/nodejs/files\fP \fI(or `debian/nodejs//files)\fR exists\. the content of this file replaces "files" entry of \fBpackage\.json\fP .RE .SS pkg\-js\-tools files .RS 0 .IP \(bu 2 all steps: .RS .IP \(bu 2 \fBdebian/nodejs/additional_components\fR is used to set some subdirectories that should be considered as components even if they are not listed in \fBdebian/watch\fP\|\. Content example: \fBpackages/*\fP\|\. \fBImportant note\fR: in this example, component name is \fBpackages/foo\fP in every other files, including paths .IP \(bu 2 \fBdebian/nodejs/main\fR is used to indicates where is the main module\. In a package containing only components \fI(bundle package)\fR, you should choose one of them as main component .RE .IP \(bu 2 configure step: .RS .IP \(bu 2 \fBdebian/build_modules\fR additional modules needed to build, will be linked in \fBnode_modules\fP directory .IP \(bu 2 \fBdebian/nodejs/component_links\fR lists needed links between components: links \fB\|\.\./\.\./component\-src\fP in \fBcomponent\-dst/node_modules/component\-src\-name\fP .IP \(bu 2 \fBdebian/nodejs//nolink\fR avoids \fBnode_modules\fP links creation for this component \fI(configuration step)\fR .IP \(bu 2 \fBdebian/nodejs/extlinks\fR lists installed node modules that should be linked into \fBnode_modules\fP directory \fI(modules are searched using nodejs algorithm)\fR\|\. You can mark them with "test" to avoid errors when build profile contains \fBnocheck\fP .IP \(bu 2 \fBdebian/nodejs/extcopies\fR lists installed node modules that should be copied into \fBnode_modules\fP directory\. You can also mark them with "test" .IP \(bu 2 \fBdebian/nodejs//extlinks\fR lists installed node modules that should be linked in \fB/node_modules\fP directory \fI(\fBtest\fP flag available)\fR .IP \(bu 2 \fBdebian/nodejs//extcopies\fR lists installed node modules that should be copied in \fB/node_modules\fP directory \fI(\fBtest\fP flag available)\fR .RE .IP \(bu 2 build step: .RS .IP \(bu 2 \fBdebian/nodejs/build\fR custom build\. An empty file stops auto build .IP \(bu 2 \fBdebian/nodejs//build\fR: same for components .IP \(bu 2 \fBdebian/nodejs/build_order\fR orders components build (one component per line)\. Else components are built in alphabetic order except components declared in \fBdebian/nodejs/component_links\fR: a component that depends on another is built after .RE .IP \(bu 2 test step: .RS .IP \(bu 2 \fBdebian/tests/test_modules\fR: additional modules needed for test, will be linked in \fBnode_modules\fP directory during test step only .IP \(bu 2 \fBdebian/tests/pkg\-js/test\fR: script to launch during test \fI(launched with \fBset \-e\fP)\fR .IP \(bu 2 \fBdebian/tests/pkg\-js/files\fR: lists other files than \fBdebian/tests/test\\_modules/\\*\fP and installed files needed for autopkgtest \fI(default: \fBtest*\fP)\fR .IP \(bu 2 \fBdebian/nodejs/test\fR: overwrite \fBdebian/tests/pkg\-js/test\fP during build if test differs in build and autopkgtest .IP \(bu 2 \fBdebian/nodejs//test\fR: same for components (launched during build only) .IP \(bu 2 \fBautopkgtest files\fR: .RS .IP \(bu 2 \fBdebian/tests/autopkgtest\-pkg\-nodejs\.conf\fR: autodep8 configuration file which can be used to add packages or restrictions during autopkgtest only .RS .IP \(bu 2 \fBextra_depends=p1, p2, p3\fP permits one to add p1, p2 and p3 packages .IP \(bu 2 \fBextra\-restrictions=needs\-internet\fP permits one to add additional restrictions during autopkgtest .RE .IP \(bu 2 \fBdebian/tests/pkg\-js/require\-name\fR: contains the name to use in autopkgtest \fBrequire\fP test instead of package\.json value .RE .RE .IP \(bu 2 install step: .RS .IP \(bu 2 \fBdebian/nodejs/submodules\fR lists components to install \fI(all if missing)\fR .IP \(bu 2 \fBdebian/nodejs/root_modules\fR lists components to install in nodejs root directory \fI(instead of \fBnode_modules\fP subdirectory)\fR\|\. If this file contains \fB*\fP, all components are installed in root directory .IP \(bu 2 \fBdebian/nodejs/files\fR overwrites \fBpackage\.json#files\fP field\. .IP \(bu 2 \fBdebian/nodejs//files\fR overwrites \fBpackage\.json#files\fP field\. An empty file avoid any install .IP \(bu 2 \fBdebian/nodejs/name\fR overwrites \fBpackage\.json#name\fP field\. .IP \(bu 2 \fBdebian/nodejs//name\fR overwrites \fBpackage\.json#name\fP .IP \(bu 2 \fBdebian/nodejs/install\fR overwrites \fBdebian/nodejs/files\fR: same usage as debian/install except that destination not starting with \fB/\fP are related to arch path \fI(\fB/usr/share/nodejs\fP or \fB/usr/lib//nodejs\fP)\fR .IP \(bu 2 \fBdebian/nodejs//install\fR same as \fBdebian/nodejs/install\fR for components .RE .IP \(bu 2 link step: .RS .IP \(bu 2 \fBdebian/nodejs/links\fR: same usage as debian/links except that source or destination not starting with \fB/\fP are related to arch path \fI(\fB/usr/share/nodejs\fP or \fB/usr/lib//nodejs\fP)\fR .RE .RE .QP .P To install a component in another directory, set its files in \fBdebian/install\fR\|\. . .P Example: .RS 0 .IP \(bu 2 debian/control .RE .P .RS 2 .nf \|\.\.\. Testsuite: autopkgtest\-pkg\-nodejs Build\-Depends: dh\-sequence\-nodejs \|\.\.\. .fi .RE .RS 0 .IP \(bu 2 debian/tests/pkg\-js/test .RE .P .RS 2 .nf mocha \-R spec .fi .RE .P See also pkg\-js\-autopkgtest README \fI\|\.\./autopkgtest/README\.md\fR\|\. .SS Multiple binary packages .P When \fBdebian/control\fP provides more than one binary package, \fBdh_auto_install\fP populates a \fBdebian/tmp\fP and \fBdh_install\fP install files in each package\. In this case, you must write a \fBdebian/\.install\fP for each binary package\. Each line with only one argument is related to \fBdebian/tmp\fP\|\. Examples: .RS 0 .IP \(bu 2 debian/node\-arch\-indep\.install: pick files from \fBdebian/tmp\fP .P .RS 2 .nf usr/share/nodejs/foo/ .fi .RE .IP \(bu 2 debian/node\-arch\-dep\.install: pick files from \fBdebian/tmp\fP .P .RS 2 .nf usr/lib/*/nodejs/foo/ .fi .RE .IP \(bu 2 debian/libjs\.install: pick files from sources .P .RS 2 .nf dist/* usr/share/javascript/foo/ .fi .RE .RE .SS Links .P Since path is not fixed for arch\-dependent package, you must write \fBdebian/nodejs/links\fP: .P .RS 2 .nf # debian/nodejs/links foo/bin/cli\.js /usr/bin/foo .fi .RE .P With a arch independent package, pkg\-js\-tools transforms this into: .P .RS 2 .nf /usr/share/nodejs/foo/bin/cli\.js /usr/bin/foo .fi .RE .P and for a arch dependent package, it uses \fBDEB_GNU_ARCH\fP\|\. Example with amd64: .P .RS 2 .nf /usr/lib/x86_64\-linux\-gnu/foo/bin/cli\.js /usr/bin/foo .fi .RE .P All fields that does not start with \fB/\fP are prefixed with the good nodejs path .SS Component docs .P Starting from version 0\.13\.0, \fBpkg\-js\-tools\fR provides \fBdh_nodejs_autodocs\fR\|\. This tool automatically install README\.md, CONTRIBUTING\.md,\.\.\. for each root component in its \fB/usr/share/doc/node\-\fP directory\. And if no \fBdebian/*docs\fP is found, it does the same for the main component\. To use it: .P .RS 2 .nf override_dh_installdocs: dh_installdocs dh_nodejs_autodocs .fi .RE .SS \|\.eslint* files .P pkg\-js\-tools auto installer always removes \fB\|\.eslint*\fP files unless it is explicitly specified in \fBdebian/nodejs/**/files\fP or \fBdebian/nodejs/**/install\fP\|\. .SS Having different test between build and autopkgtest .P When \fBdebian/nodejs/test\fP exists, this file is used during build test instead of \fBdebian/tests/pkg\-js/test\fP\|\. This permits one to have a different test\. You can also overwrite \fBdh_auto_test\fP step in \fBdebian/rules\fP: .P .RS 2 .nf override_dh_auto_test: # No test during build (test needs Internet) .fi .RE .SS Autopkgtest additional test packages or test restrictions .P autodep8 allows one to add additional packages during autopkgtest (and/or additional restrictions) by using a debian/tests/autopkgtest\-pkg\-nodejs\.conf file: .P .RS 2 .nf extra_depends=mocha, npm extra\-restrictions=needs\-internet .fi .RE .SH LINTIAN PROFILES .P pkg\-js\-tools provides a lintian profile: .RS 0 .IP \(bu 2 pkg\-js\-extra: launches additional checks \fI(repo consistency see debcheck\-node\-repo below)\fR .RE .P To use them: .P .RS 2 .nf lintian \-\-profile pkg\-js\-extra \.\./node\-foo_1\.2\.3\-1\.changes .fi .RE .SH OTHER TOOLS .P See related manpages\. .RS 0 .IP \(bu 2 \fBadd\-node\-component\fR: automatically modifies gbp\.conf and debian/watch to add a node component\. See JS Group Sources Tutorial \fIhttps://wiki\.debian\.org/Javascript/GroupSourcesTutorial\fR\|\. It can also list components or modules (real names) .IP \(bu 2 \fBgetFromNpmCache\fR: export npm cache content to standard output .IP \(bu 2 \fBgithub\-debian\-upstream\fR: launches it in source repo to create a debian/upstream/metadata \fI(works only if upstream repo is on GitHub)\fR .IP \(bu 2 \fBnodepath\fR: shows the path of a node module (npm name)\. You can use \fB\-p\fP to show also the Debian package\. Option \fB\-o\fP shows only Debian package name\. .IP \(bu 2 \fBdebcheck\-node\-repo\fR: checks repo consistency: compares vcs repo registered in npm registry with the source repo declared in debian/watch" .IP \(bu 2 \fBdh_nodejs_autodocs\fR: automatically select and install documentation files toinstall for each component .IP \(bu 2 \fBdh_nodejs_build_debug_package\fR: move sourcemap files from binary packages to a separated debug package .IP \(bu 2 \fBmjs2cjs\fR: build commonjs file using rollup .IP \(bu 2 \fBpkgjs\-audit\fR: creates a temporary \fBpackage\-lock\.json\fP file using Debian package values used by the module to analyze, and launch a \fBnpm audit\fP\|\. If module is a bundle \fI(and then has a \fBpkgjs\-lock\.json\fP)\fR, pkgjs\-audit uses \fBpkgjs\-lock\.json\fP, else it generates its package\-lock\.json using available values .IP \(bu 2 \fBpkgjs\-depends\fR: search recursively dependencies of the given module name (if not given, use current package\.json) and displays related Debian packages and missing dependencies .IP \(bu 2 \fBpkgjs\-install\fR: same as \fBnpm install\fP but uses Debian JS modules when available .IP \(bu 2 \fBpkgjs\-install\-minimal\fR: same as pkgjs\-install but uses only available Debian modules\. It is included in dh\-nodejs so can be used during build .IP \(bu 2 \fBpkgjs\-ls\fR: same as \fBnpm ls\fP but it search also in global nodejs paths .IP \(bu 2 \fBpkgjs\-run\fR: same as \fBnpm run\fP .IP \(bu 2 \fBpkgjs\-utils\fR, \fBpkgjs\-ln\fR, \fBpkgjs\-main\fR, \fBpkgjs\-pjson\fR: various utilities\. See \fBpkgjs\-utils(1)\fP manpage\. .RE .SH SEE ALSO .P 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) .SH FEATURES HISTORY .TS tab(|) expand nowarn box; l l. T{ TOOL T}|T{ Minimal version T} _ T{ add\-node\-component T}|T{ 0\.8\.14 T} T{ add\-node\-component \-\-cmp\-tree T}|T{ 0\.9\.22 T} T{ debcheck\-node\-repo T}|T{ 0\.8\.14 T} T{ dh_nodejs_autodocs T}|T{ 0\.13\.0 T} T{ dh_nodejs_autodocs auto_dispatch T}|T{ 0\.14\.5 T} T{ dh_nodejs_build_debug_package T}|T{ 0\.15\.5 T} T{ dh_nodejs_substvars T}|T{ 0\.14\.5 T} T{ dh\-make\-node T}|T{ 0\.9\.18 T} T{ getFromNpmCache T}|T{ 0\.14\.32 T} T{ mjs2cjs T}|T{ 0\.12\.3 T} T{ mjs2cjs \-a T}|T{ 0\.14\.14 T} T{ pkgjs\-audit T}|T{ 0\.11\.2 T} T{ pkgjs\-depends T}|T{ 0\.9\.54 T} T{ pkgjs\-depends \-\-graph T}|T{ 0\.14\.34 T} T{ pkgjs\-install T}|T{ 0\.14\.20 T} T{ pkgjs\-install\-minimal T}|T{ 0\.14\.27 T} T{ pkgjs\-ln T}|T{ 0\.9\.76 T} T{ pkgjs\-ls T}|T{ 0\.9\.30 T} T{ pkgjs\-main T}|T{ 0\.9\.76 T} T{ pkgjs\-pjson T}|T{ 0\.9\.76 T} T{ pkgjs\-run T}|T{ 0\.14\.22 T} T{ pkgjs\-utils T}|T{ 0\.9\.75 T} .TE .TS tab(|) expand nowarn box; l l. T{ FEATURE T}|T{ Minimal version T} _ T{ additional_components T}|T{ 0\.9\.11 T} T{ auto build (grunt) T}|T{ 0\.9\.3 T} T{ autopkgtest skip T}|T{ 0\.9\.30 T} T{ auto\-install (arch\-dep) T}|T{ 0\.9\.27 T} T{ build order T}|T{ 0\.9\.10 T} T{ dh\-sequence\-nodejs T}|T{ 0\.9\.41 T} T{ follow lerna\.json#useWorkspaces T}|T{ 0\.14\.8 T} T{ \|\.npmignore support T}|T{ 0\.9\.53 T} T{ support lerna\.conf T}|T{ 0\.12\.0 T} T{ support workspaces T}|T{ 0\.12\.7 T} T{ debian/nodejs/main T}|T{ 0\.9\.11 T} T{ debian/tests/test_modules T}|T{ 0\.9\.33 T} T{ debian/build_modules T}|T{ 0\.9\.33 T} T{ ${nodejs:BuiltUsing} T}|T{ 0\.11\.8 T} T{ ${nodejs:Provides} T}|T{ 0\.9\.10 T} T{ ${nodejs:Version} T}|T{ 0\.9\.38 T} T{ ${nodeFoo:Provides} T}|T{ 0\.14\.5 T} .TE .SH COPYRIGHT AND LICENSE .P Copyright Yadd .P 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\. .P 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\. .P 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 \fIhttp://www\.gnu\.org/licenses/\fR;