Differences between revisions 4 and 6 (spanning 2 versions)
Revision 4 as of 2014-04-15 11:16:01
Size: 3411
Editor: LeoIannacone
Comment: Added some info take from Javascript/Policy - page must be reviewed
Revision 6 as of 2014-05-10 12:57:38
Size: 3657
Editor: LeoIannacone
Comment: updated.
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
## page was renamed from Javascript/nodejs
= Node.js modules best practice (draft) =
{{{#!wiki caution
'''This document is still work in progress.'''
Line 4: Line 4:
== Package naming ==

The ''binary'' package name '''must''' be called '''node-foo''', and the ''source'' package name '''should''' be called the same

{{{#!wiki note
if the library is usable both from a web-browser ''and'' from NodeJS, it should generate ''two binary packages'', each called as described above and in [[Javascript/Policy|Policy]] page.
Please check the [[http://lists.alioth.debian.org/pipermail/pkg-javascript-devel/|mailing list archives]] for the latest discussions about it.
Line 12: Line 7:
== Paths ==
The scripts should be installed to `/usr/lib/nodejs/` or `/usr/lib/nodejs/foo/`. The choice depends whether the module is contained in a single file or in multiple files. In case the latter is true, please refer to the [[http://nodejs.org/docs/latest/api/modules.html#folders_as_Modules|upstream documentation]] (also available in `/usr/share/doc/nodejs/api/modules.html#folders_as_Modules`) to understand how to correctly make it available to the NodeJS framework.
= Node.js modules policy =
Line 15: Line 9:
== Intro ==

Loading a module in Node.js is done with
{{{
var mymod = require("somepathtomymod");
}}}

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

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 37: Line 12:
== how to install a module == = Policy in brief =

 0. the ''binary'' package name '''must''' be called '''node-foo''' and the ''source'' package name '''should''' be called the same
 
 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)


= Policy in details =

== Install ==
Line 44: Line 34:
   {{{
   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 50: Line 41:
   {{{
   usr/lib/nodejs/<module>/bin/<mybin>.js usr/bin/<mybinOrRenameProperly>
   }}}
 {{{
usr/lib/nodejs/<module>/bin/<mybin>.js usr/bin/<mybinOrRenameProperly>
}}}
Line 54: Line 45:
   {{{
   usr/bin
   }}}
 {{{
usr/bin
}}}
Line 64: Line 55:
== 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.
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 77: Line 58:
== Binary rename of node to nodejs == == 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.
Line 79: Line 61:
The program name "node" is conflicting with another package. 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.


== 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.
Line 81: Line 78:
To comply to this, it is often as simple as :
 * Depends nodejs

To comply to this, it is often as simple as:

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 package name must be called node-foo and the source package name should be called the same

  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-broser (see Javascript/Policy) for more info)

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.

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.