Differences between revisions 3 and 4
Revision 3 as of 2014-04-15 10:39:32
Size: 2056
Editor: LeoIannacone
Comment: Renamed as subpage of Nodejs
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
Deletions are marked like this. Additions are marked like this.
Line 4: Line 4:
== intro == == 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.
}}}

== 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.

== Intro ==
Line 64: Line 75:


== Binary rename of node to nodejs ==

The program name "node" is conflicting with another package.
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 :
 * Depends nodejs
 * 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.

Node.js modules best practice (draft)

Package naming

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

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 Policy page.

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 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.

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.

how to install a module

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

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.

Binary rename of node to nodejs

The program name "node" is conflicting with another package. Technical committee decided to fix this by renaming node to nodejs. To comply to this, it is often as simple as :

  • Depends nodejs
  • 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.