2012
Comment:
|
4637
Add node about script
|
Deletions are marked like this. | Additions are marked like this. |
Line 1: | Line 1: |
= Node.js modules best practice (draft) = | {{{#!wiki caution '''This document is still work in progress.''' |
Line 3: | Line 4: |
== intro == Loading a module in Node.js is done with {{{ var mymod = require("somepathtomymod"); |
Please check the [[http://lists.alioth.debian.org/pipermail/pkg-javascript-devel/|mailing list archives]] for the latest discussions about it. |
Line 10: | Line 7: |
The path of the module refers to : * a file * a directory that contains an index.js file * a directory that contains a package.json file * a package.json file |
= Node.js modules policy = |
Line 16: | Line 9: |
The path itself can be in Node.js search path (NODE_PATH, see Node.js documentation), or an absolute or relative filesystem path. Because of the plurality of ways to load a module, it is inevitable there is a plurality of ways to (debian-)package and install a module. This page tries to explain the best and most compatible way to install a module. |
This page describes the policy that packages with '''Node.js''' modules should follow. |
Line 25: | Line 12: |
== how to install a module == | = Policy in brief = 0. the ''binary'' and the ''source'' package '''should''' be called '''node-foo''' 0. '''must''' build depends on ''nodejs'' 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 0. '''should''' have `package.json` shipped in `/usr/lib/nodejs/foo/package.json` 0. '''should''' generate a '''libjs-foo''' binary package if the script is usable also for web-broser (see [[Javascript/Policy]] for more info) 0. '''should''' integrate [[#autopkgtest|automatic tests]] checking `require('foo')` works correctly = Policy in details = == Install == |
Line 32: | Line 36: |
{{{ lib usr/lib/nodejs/<module> bin usr/lib/nodejs/<module> package.json usr/lib/nodejs/<module> }}} |
{{{ lib usr/lib/nodejs/<module> bin usr/lib/nodejs/<module> package.json usr/lib/nodejs/<module> }}} |
Line 38: | Line 43: |
{{{ usr/lib/nodejs/<module>/bin/<mybin>.js usr/bin/<mybinOrRenameProperly> }}} |
{{{ usr/lib/nodejs/<module>/bin/<mybin>.js usr/bin/<mybinOrRenameProperly> }}} |
Line 42: | Line 47: |
{{{ usr/bin }}} |
{{{ usr/bin }}} |
Line 52: | Line 57: |
== declare a build-dependency on nodejs == | Please refer to the [[http://nodejs.org/docs/latest/api/modules.html#modules_folders_as_modules|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. |
Line 54: | Line 59: |
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". |
|
Line 61: | Line 60: |
Declaring that build-dependency is also quite natural in the case of a package running its test suite during its build. |
== 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 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. <<Anchor(autopkgtest)>> == Autopkgtest - automatic tests == The package should provide automatic tests to check `require(foo);` works correctly in Debian. For more information about '''autopkgtest''', please see [[http://dep.debian.net/deps/dep8/|DEP 8 specification]]. This script can help you to add automatically autopkgtest support to your packages: {{attachment:node-autopkgtest.sh}} If you want edit manually your package, you must do the following: * add this line to `debian/control` {{{ XS-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: {{{#!bash #!/bin/sh set -e nodejs -e "require('foo');" }}} replace '''foo''' with the correct name of the module provided along with the package. == Patching binaries shebang == While the entire world use '''node''' as command name for Node.js framework, in Debian the correct name is '''nodejs''', because it conflicts with another package called ''node'' as well. Technical committee decided to fix this by [[http://bugs.debian.org/614907#108|renaming node to nodejs]]. To comply to this, it is often as simple as: * change shebangs to #!/usr/bin/nodejs * rename node to nodejs in makefiles * do not depend on nodejs-legacy Some programs are a bit less obvious to fix, for example they can spawn nodejs instances using "node" name. |
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
the binary and the source package should be called node-foo
must build depends on nodejs
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
should have package.json shipped in /usr/lib/nodejs/foo/package.json
should generate a libjs-foo binary package if the script is usable also for web-broser (see Javascript/Policy for more info)
should integrate automatic tests checking require('foo') works correctly
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 (except for the nodejs rename):
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 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:
If you want edit manually your package, you must do the following:
add this line to debian/control
XS-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 nodejs -e "require('foo');"
replace foo with the correct name of the module provided along with the package.
Patching binaries shebang
While the entire world use node as command name for Node.js framework, in Debian the correct name is nodejs, because it conflicts with another package called node as well.
Technical committee decided to fix this by renaming node to nodejs.
To comply to this, it is often as simple as:
- change shebangs to #!/usr/bin/nodejs
- rename node to nodejs in makefiles
- do not depend on nodejs-legacy
Some programs are a bit less obvious to fix, for example they can spawn nodejs instances using "node" name.