Differences between revisions 19 and 22 (spanning 3 versions)
Revision 19 as of 2017-08-16 06:43:15
Size: 6259
Editor: RossGammon
Comment: Rename nodejs back to node!
Revision 22 as of 2017-10-30 11:06:24
Size: 6306
Editor: ?PaoloGreppi
Comment:
Deletions are marked like this. Additions are marked like this.
Line 18: Line 18:
 0. '''should''' be installed to `/usr/lib/node/` or `/usr/lib/node/foo/`, depends whether the module is contained in a single file or in multiple files  0. '''should''' be installed to `/usr/lib/nodejs/` or `/usr/lib/nodejs/foo/`, depends whether the module is contained in a single file or in multiple files
Line 20: Line 20:
 0. '''should''' have `package.json` shipped in `/usr/lib/node/foo/package.json`  0. '''should''' have `package.json` shipped in `/usr/lib/nodejs/foo/package.json`
Line 39: Line 39:
lib usr/lib/node/<module>
bin usr/lib/node/<module>
package.json usr/lib/node/<module>
lib usr/lib/nodejs/<module>
bin usr/lib/nodejs/<module>
package.json usr/lib/nodejs/<module>
Line 46: Line 46:
usr/lib/node/<module>/bin/<mybin>.js usr/bin/<mybinOrRenameProperly> usr/lib/nodejs/<module>/bin/<mybin>.js usr/bin/<mybinOrRenameProperly>
Line 65: Line 65:
Minified files and browserified files are examples of such files that could be excluded for that reason. A convenient way to achieve this is to use the Files-Excluded field in debian/copyright, for more information please see UscanEnhancements. Minified files and browserified files are examples of such files that could be excluded for that reason. A convenient way to achieve this is to use the Files-Excluded field in debian/copyright, for more information please see [[Javascript/Repacking]] and [[UscanEnhancements]].
Line 116: Line 116:
Now that the original node package has been removed from Debian, the Technical committee has reversed its decision [[https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=862051|Rename nodejs back to node for buster]. Therefore, uploads to unstable shall now drop the old patches which rename node to nodejs. Now that the original node package has been removed from Debian, the Technical committee has reversed its decision [[https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=862051|Rename nodejs back to node for buster]]. Therefore, uploads to unstable shall now drop the old patches which rename node to nodejs.
Line 154: Line 154:
No, though i propose to make it a release goal for Stretch. Yes, we think this is a realistic release goal for Buster.

This document is still work in progress.

Please check the mailing list archives for the latest discussions about it.

Node.js modules policy

This page describes the policy that packages with Node.js modules should follow.

Policy in brief

  1. the binary and the source package should be called node-foo

  2. must build depends on nodejs

  3. should be installed to /usr/lib/nodejs/ or /usr/lib/nodejs/foo/, depends whether the module is contained in a single file or in multiple files

  4. should have package.json shipped in /usr/lib/nodejs/foo/package.json

  5. should generate a libjs-foo binary package if the script is usable also for web-browser (see Javascript/Policy for more info)

  6. should integrate automatic tests checking require('foo') works correctly

  7. compiled c++ addons should Depend on nodejs-abi-<process.versions.modules>

Policy in details

Install

A module typically has already a source tree layout with directories like "lib", "bin", and a package.json file at its root.

Installing is as simple as:

  • debian/install
    lib          usr/lib/nodejs/<module>
    bin          usr/lib/nodejs/<module>
    package.json usr/lib/nodejs/<module>
  • debian/links
    usr/lib/nodejs/<module>/bin/<mybin>.js   usr/bin/<mybinOrRenameProperly>
  • debian/dirs
    usr/bin

This usually allows source to be kept unpatched:

  • relative require statements like  require('..')  work

  • lookups in package.json like  require('./package').version 

  • load module from NODE_PATH :  require('mymodule');  still work

Please refer to the upstream documentation (also available in /usr/share/doc/nodejs/api/modules.html#modules_folders_as_modules) to understand how to correctly Node.js looks up for modules.

Excluding auto-generated files from source

Strict application of DFSG requires files generated from source in upstream tarball to be excluded, unless it is possible to regenerate the files and prove they are identical to the ones in the tarball.

Minified files and browserified files are examples of such files that could be excluded for that reason. A convenient way to achieve this is to use the Files-Excluded field in debian/copyright, for more information please see Javascript/Repacking and UscanEnhancements.

Declare a build-dependency on nodejs

The nodejs package depends on libv8 and doesn't build on some architectures. Because of that, node-* packages having "Architecture: all" are available on architectures where nodejs isn't available - and so are uninstallable on those architectures. To work around that inconvenience to the users, simply declare an unversioned "Build-Depends: nodejs".

Declaring that build-dependency is also quite natural in the case of a package running its test suite during its build.

Autopkgtest - automatic tests

The package should provide automatic tests to check require(foo); works correctly in Debian. For more information about autopkgtest, please see DEP 8 specification.

This script can help you to add automatically autopkgtest support to your packages: node-autopkgtest.sh

If you want edit manually your package, you must do the following:

  • add this line to debian/control

    Testsuite: autopkgtest
  • create debian/tests/control and put:

    Tests: require
    Depends: node-foo

    replace node-foo with the name of the binary package contains the module foo

  • create debian/tests/require and put:

    #!/bin/sh
    set -e
    node -e "require('foo');"

    replace foo with the correct name of the module provided along with the package.

Patching binaries shebang

While the entire world used node as command name for Node.js framework, in Debian the correct name was nodejs, because it conflicted with another package called node as well.

Technical committee decided to fix this by renaming node to nodejs.

To comply to this, node packages required patching, for example:

  • change shebangs to #!/usr/bin/nodejs
  • rename node to nodejs in makefiles
  • do not depend on nodejs-legacy

Now that the original node package has been removed from Debian, the Technical committee has reversed its decision Rename nodejs back to node for buster. Therefore, uploads to unstable shall now drop the old patches which rename node to nodejs.

Declaring a dependency on nodejs-abi-<process.versions.modules> for c++ addons

nodejs (>= 4.1.2~) provides a virtual package called nodejs-abi-<version>, where <version> is obtained with nodejs -e "console.log(process.versions.modules)" (or similar). This allows c++ addons compiled using nodejs-dev or node-gyp to declare a dependency upon a specific nodejs modules ABI.

Many thanks to Jonas Smedegaard for the idea https://bugs.debian.org/785748 and the essential part of the work.

Why Depend: nodejs-abi-<version>

It makes transitioning compiled Node.js addons to newer Node.js versions less painful. Without that, a bump in the abi means all packaged c++ addons report runtime failures. With that, a systematic binNMU of all concerned packages can be requested, and build failures can be dealt with properly.

See also https://bugs.debian.org/685540#20 for an example about how binNMU-ability is important.

How to use it ?

Build-Depends: nodejs-dev (>= 4.1.2~)

For dh-style packages

  • Using a dh addon:

    dh $@ --with nodejs
  • or the dh_nodejs helper:

    override_dh_install:
      dh_nodejs

For cdbs-style packages

binary-post-install/$(pkg):
  dh_nodejs -p$(cdbs_curpkg)

Is it mandatory ?

Yes, we think this is a realistic release goal for Buster.