From 43bc1d7ec89031c50f799a7b0964dcc22d24129c Mon Sep 17 00:00:00 2001 From: Ryan Dahl Date: Wed, 9 Feb 2011 17:48:22 -0800 Subject: [PATCH] Edit module docs --- doc/api/modules.markdown | 76 +++++++++++++++++----------------------- 1 file changed, 32 insertions(+), 44 deletions(-) diff --git a/doc/api/modules.markdown b/doc/api/modules.markdown index 425f77c5af..35cdbac8b4 100644 --- a/doc/api/modules.markdown +++ b/doc/api/modules.markdown @@ -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 Node uses the CommonJS module system. @@ -273,51 +260,52 @@ that are difficult to predict. ## Addenda: Package Manager Tips -If you were to build a package manager, the tools above provide you with -all you need to very elegantly set up modules in a folder structure such -that they get the required dependencies and do not conflict with one -another. +The semantics of Node's `require()` function were designed to be general +enough to support a number of sane directory structures. Package manager +programs such as `dpkg`, `rpm`, and `npm` will hopefully find it possible to +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 -`/usr/lib//` hold the contents of a specific -version of a package. +`/usr/lib/node//` hold the contents of a +specific version of a package. -Packages can depend on one another. So, in order to install -package `foo`, you may have to install a specific version of package `bar`. -The `bar` package may itself have dependencies, and in some cases, these -dependencies may even collide or form cycles. +Packages can depend on one another. In order to install package `foo`, you +may have to install a specific version of package `bar`. The `bar` package +may itself have dependencies, and in some cases, these dependencies may even +collide or form cycles. -Since Node looks up the `realpath` of any modules it loads, and then -looks for their dependencies in the `node_modules` folders as described -above, this situation is very simple to resolve with the following -architecture: +Since Node looks up the `realpath` of any modules it loads (that is, +resolves symlinks), and then looks for their dependencies in the +`node_modules` folders as described above, this situation is very simple to +resolve with the following architecture: -* `/usr/lib/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/foo/1.2.3/` - Contents of the `foo` package, version 1.2.3. +* `/usr/lib/node/bar/4.3.2/` - Contents of the `bar` package that `foo` depends on. -* `/usr/lib/foo/1.2.3/node_modules/bar` - Symbolic link to - `/usr/lib/bar/4.3.2/`. -* `/usr/lib/bar/4.3.2/node_modules/*` - Symbolic links to the packages +* `/usr/lib/node/foo/1.2.3/node_modules/bar` - Symbolic link to + `/usr/lib/node/bar/4.3.2/`. +* `/usr/lib/node/bar/4.3.2/node_modules/*` - Symbolic links to the packages that `bar` depends on. 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 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 -`/usr/lib/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 `/usr/lib/bar/4.3.2/node_modules/quux`. +`/usr/lib/node/bar/4.3.2/node_modules/quux`. 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//`. Then node will not bother -looking for missing dependencies in `/usr/node_modules` or -`/node_modules`. +looking for missing dependencies in `/usr/node_modules` or `/node_modules`. -In order to make modules available to the node repl, it might be useful -to also add the `/usr/lib/node_modules` folder to the `NODE_PATH` -environment variable. Since the module lookups using `node_modules` -folders are all relative, and based on the real path of the files -making the calls to `require()`, the packages themselves can be anywhere. +In order to make modules available to the node REPL, it might be useful to +also add the `/usr/lib/node_modules` folder to the `$NODE_PATH` environment +variable. Since the module lookups using `node_modules` folders are all +relative, and based on the real path of the files making the calls to +`require()`, the packages themselves can be anywhere.