1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Edit module docs

Browse Source
This commit is contained in:
Ryan Dahl 2011-02-09 17:48:22 -08:00
parent ff39d413a3
commit 43bc1d7ec8
1 changed files with 32 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

76
doc/api/modules.markdown
View File

@ -1,16 +1,3 @@
## Standard Modules
Node comes with a number of modules that are compiled in to the process,
most of which are documented below. The most common way to use these modules
is with `require('name')` and then assigning the return value to a local
variable with the same name as the module.
Example:
var util = require('util');
It is possible to extend node with other modules. See `'Modules'`
## Modules ## Modules
Node uses the CommonJS module system. Node uses the CommonJS module system.
@ -273,51 +260,52 @@ that are difficult to predict.
## Addenda: Package Manager Tips ## Addenda: Package Manager Tips
If you were to build a package manager, the tools above provide you with The semantics of Node's `require()` function were designed to be general
all you need to very elegantly set up modules in a folder structure such enough to support a number of sane directory structures. Package manager
that they get the required dependencies and do not conflict with one programs such as `dpkg`, `rpm`, and `npm` will hopefully find it possible to
another. build native packages from Node modules without modification.
Below we give a suggested directory structure that could work:
Let's say that we wanted to have the folder at Let's say that we wanted to have the folder at
`/usr/lib/<some-program>/<some-version>` hold the contents of a specific `/usr/lib/node/<some-package>/<some-version>` hold the contents of a
version of a package. specific version of a package.
Packages can depend on one another. So, in order to install Packages can depend on one another. In order to install package `foo`, you
package `foo`, you may have to install a specific version of package `bar`. may have to install a specific version of package `bar`. The `bar` package
The `bar` package may itself have dependencies, and in some cases, these may itself have dependencies, and in some cases, these dependencies may even
dependencies may even collide or form cycles. collide or form cycles.
Since Node looks up the `realpath` of any modules it loads, and then Since Node looks up the `realpath` of any modules it loads (that is,
looks for their dependencies in the `node_modules` folders as described resolves symlinks), and then looks for their dependencies in the
above, this situation is very simple to resolve with the following `node_modules` folders as described above, this situation is very simple to
architecture: resolve with the following architecture:
* `/usr/lib/foo/1.2.3/` - Contents of the `foo` package, version 1.2.3. * `/usr/lib/node/foo/1.2.3/` - Contents of the `foo` package, version 1.2.3.
* `/usr/lib/bar/4.3.2/` - Contents of the `bar` package that `foo` * `/usr/lib/node/bar/4.3.2/` - Contents of the `bar` package that `foo`
depends on. depends on.
* `/usr/lib/foo/1.2.3/node_modules/bar` - Symbolic link to * `/usr/lib/node/foo/1.2.3/node_modules/bar` - Symbolic link to
`/usr/lib/bar/4.3.2/`. `/usr/lib/node/bar/4.3.2/`.
* `/usr/lib/bar/4.3.2/node_modules/*` - Symbolic links to the packages * `/usr/lib/node/bar/4.3.2/node_modules/*` - Symbolic links to the packages
that `bar` depends on. that `bar` depends on.
Thus, even if a cycle is encountered, or if there are dependency Thus, even if a cycle is encountered, or if there are dependency
conflicts, every module will be able to get a version of its dependency conflicts, every module will be able to get a version of its dependency
that it can use. that it can use.
When the code in the `foo` package does `require('bar')`, it will get When the code in the `foo` package does `require('bar')`, it will get the
version that is symlinked into `/usr/lib/node/foo/1.2.3/node_modules/bar`.
Then, when the code in the `bar` package calls `require('quux')`, it'll get
the version that is symlinked into the version that is symlinked into
`/usr/lib/foo/1.2.3/node_modules/bar`. Then, when the code in the `bar` `/usr/lib/node/bar/4.3.2/node_modules/quux`.
package calls `require('quux')`, it'll get the version that is symlinked
into `/usr/lib/bar/4.3.2/node_modules/quux`.
Furthermore, to make the module lookup process even more optimal, rather Furthermore, to make the module lookup process even more optimal, rather
than putting packages directly in `/usr/lib`, we could put them in than putting packages directly in `/usr/lib/node`, we could put them in
`/usr/lib/node_modules/<name>/<version>`. Then node will not bother `/usr/lib/node_modules/<name>/<version>`. Then node will not bother
looking for missing dependencies in `/usr/node_modules` or looking for missing dependencies in `/usr/node_modules` or `/node_modules`.
`/node_modules`.
In order to make modules available to the node repl, it might be useful In order to make modules available to the node REPL, it might be useful to
to also add the `/usr/lib/node_modules` folder to the `NODE_PATH` also add the `/usr/lib/node_modules` folder to the `$NODE_PATH` environment
environment variable. Since the module lookups using `node_modules` variable. Since the module lookups using `node_modules` folders are all
folders are all relative, and based on the real path of the files relative, and based on the real path of the files making the calls to
making the calls to `require()`, the packages themselves can be anywhere. `require()`, the packages themselves can be anywhere.