From a3229ed7b7abff0b617db4a1b75121befc20c68b Mon Sep 17 00:00:00 2001 From: Ryan Dahl Date: Wed, 23 Sep 2009 16:53:31 +0200 Subject: [PATCH] Add documentation about requiring system modules. --- doc/api.html | 28 +++++++++++++++++++++------- doc/api.txt | 31 ++++++++++++++++++++++++------- doc/node.1 | 21 +++++++++++++++------ 3 files changed, 60 insertions(+), 20 deletions(-) diff --git a/doc/api.html b/doc/api.html index 6f33722f59..b75fa1204f 100644 --- a/doc/api.html +++ b/doc/api.html @@ -449,11 +449,6 @@ private to circle.js.

The module path is relative to the file calling require(). That is, circle.js must be in the same directory as foo.js for require() to find it.

-

HTTP URLs can also be used to load modules. For example,

-
-
-
var circle = require("http://tinyclouds.org/node/circle.js");
-

Like require() the function include() also loads a module. Instead of returning a namespace object, include() will add the module’s exports into the global namespace. For example:

@@ -462,7 +457,26 @@ the global namespace. For example:

include("circle.js");
 puts("The area of a cirlce of radius 4 is " + area(4));
-

Functions require_async() and include_async() also exist.

+

When an absolute path is given to require() or include(), like +require("/mjsunit.js") the module is searched for in the +node.libraryPaths array. node.libraryPaths on my system looks like this:

+
+
+
[ "/home/ryan/.node_libraries"
+, "/home/ryan/local/node/lib/node_libraries"
+, "/"
+]
+
+

That is, first Node looks for "/home/ryan/.node_libraries/mjsunit.js" and +then for "/home/ryan/local/node/lib/node_libraries/mjsunit.js". If not +found, it finally looks for "/mjsunit.js" (in the root directory).

+

node.libraryPaths can be modified at runtime by simply unshifting new +paths on to it and at startup with the NODE_LIBRARY_PATHS environmental +variable (which should be a list of paths, colon separated).

+

Node comes with several libraries which are installed when "make install" +is run. These are currently undocumented, but do look them up in your +system.

+

(Functions require_async() and include_async() also exist.)

process.addListener("exit", function () { })

When the program exits a special object called process will emit an "exit" event.

@@ -1932,7 +1946,7 @@ init (Handle<Object> target) diff --git a/doc/api.txt b/doc/api.txt index c3525938a6..b9ed53bb3e 100644 --- a/doc/api.txt +++ b/doc/api.txt @@ -277,12 +277,6 @@ The module path is relative to the file calling +require()+. That is, +circle.js+ must be in the same directory as +foo.js+ for +require()+ to find it. -HTTP URLs can also be used to load modules. For example, - ----------------------------------------- -var circle = require("http://tinyclouds.org/node/circle.js"); ----------------------------------------- - Like +require()+ the function +include()+ also loads a module. Instead of returning a namespace object, +include()+ will add the module's exports into the global namespace. For example: @@ -292,7 +286,30 @@ include("circle.js"); puts("The area of a cirlce of radius 4 is " + area(4)); ---------------------------------------- -Functions +require_async()+ and +include_async()+ also exist. +When an absolute path is given to +require()+ or +include()+, like ++require("/mjsunit.js")+ the module is searched for in the ++node.libraryPaths+ array. +node.libraryPaths+ on my system looks like this: + +---------------------------------------- +[ "/home/ryan/.node_libraries" +, "/home/ryan/local/node/lib/node_libraries" +, "/" +] +---------------------------------------- + +That is, first Node looks for +"/home/ryan/.node_libraries/mjsunit.js"+ and +then for +"/home/ryan/local/node/lib/node_libraries/mjsunit.js"+. If not +found, it finally looks for +"/mjsunit.js"+ (in the root directory). + ++node.libraryPaths+ can be modified at runtime by simply unshifting new +paths on to it and at startup with the +NODE_LIBRARY_PATHS+ environmental +variable (which should be a list of paths, colon separated). + +Node comes with several libraries which are installed when +"make install"+ +is run. These are currently undocumented, but do look them up in your +system. + +(Functions +require_async()+ and +include_async()+ also exist.) ==== +process.addListener("exit", function () { })+ diff --git a/doc/node.1 b/doc/node.1 index f04a2e68a1..bd8e7b6b59 100644 --- a/doc/node.1 +++ b/doc/node.1 @@ -398,24 +398,33 @@ The module circle\.js has exported the functions area() and circumference()\. To .sp The module path is relative to the file calling require()\. That is, circle\.js must be in the same directory as foo\.js for require() to find it\. .sp -HTTP URLs can also be used to load modules\. For example, +Like require() the function include() also loads a module\. Instead of returning a namespace object, include() will add the module\(cqs exports into the global namespace\. For example: .sp .sp .RS 4 .nf -var circle = require("http://tinyclouds\.org/node/circle\.js"); +include("circle\.js"); +puts("The area of a cirlce of radius 4 is " + area(4)); .fi .RE -Like require() the function include() also loads a module\. Instead of returning a namespace object, include() will add the module\(cqs exports into the global namespace\. For example: +When an absolute path is given to require() or include(), like require("/mjsunit\.js") the module is searched for in the node\.libraryPaths array\. node\.libraryPaths on my system looks like this: .sp .sp .RS 4 .nf -include("circle\.js"); -puts("The area of a cirlce of radius 4 is " + area(4)); +[ "/home/ryan/\.node_libraries" +, "/home/ryan/local/node/lib/node_libraries" +, "/" +] .fi .RE -Functions require_async() and include_async() also exist\. +That is, first Node looks for "/home/ryan/\.node_libraries/mjsunit\.js" and then for "/home/ryan/local/node/lib/node_libraries/mjsunit\.js"\. If not found, it finally looks for "/mjsunit\.js" (in the root directory)\. +.sp +node\.libraryPaths can be modified at runtime by simply unshifting new paths on to it and at startup with the NODE_LIBRARY_PATHS environmental variable (which should be a list of paths, colon separated)\. +.sp +Node comes with several libraries which are installed when "make install" is run\. These are currently undocumented, but do look them up in your system\. +.sp +(Functions require_async() and include_async() also exist\.) .sp .sp .it 1 an-trap