Update addon documentation

1 files changed, 44 insertions, 32 deletions

diff --git a/doc/api.txt b/doc/api.txt
index 098364301..547d8aebd 100644
--- a/doc/api.txt
+++ b/doc/api.txt
@@ -1260,10 +1260,11 @@ require("/repl.js").start("simple tcp server> ");
 
 
 
-== Extension API
+== Addons
 
-External modules can be compiled and dynamically linked into Node. 
-Node is more or less glue between several C and C++ libraries:
+Addons are dynamically linked shared objects. They can provide glue to C and
+C++ libraries. The API (at the moment) is rather complex, involving
+knowledge of several libraries:
 
  - V8 Javascript, a C++ library. Used for interfacing with Javascript:
    creating objects, calling functions, etc.  Documented mostly in the
@@ -1289,39 +1290,18 @@ Node statically compiles all its dependencies into the executable. When
 compiling your module, you don't need to worry about linking to any of these
 libraries. 
 
-Here is a sample Makefile taken from 
-http://github.com/ry/node_postgres[node_postgres]:
+To get started let's make a small Addon which does the following except in
+C++:
 -----------------------------------------------------
-binding.node: binding.o Makefile
-	gcc -shared -o binding.node  binding.o \
-		-L`pg_config --libdir` -lpq
-
-binding.o: binding.cc Makefile
-	gcc `node --cflags` -I`pg_config --includedir` \
-		binding.cc -c -o binding.o
-
-clean:
-	rm -f binding.o binding.node
-.PHONY: clean
+exports.hello = "world";
 -----------------------------------------------------
-As you can see, the only thing your module needs to know about Node is the
-CFLAGS that node was compiled with which are gotten from +node --cflags+
-If you want to make a debug build, then use +node_g --cflags+. (+node_g+ is
-the debug build of node, which can built with +configure --debug; make; make
-install+.)
-
-Node extension modules are dynamically linked libraries with a +.node+
-extension. Node opens this file and looks for a function called +init()+
-which must be of the form:
 
+To get started we create a file +hello.cc+:
 -----------------------------------------------------
-extern "C" void init (Handle<Object> target) 
------------------------------------------------------
+#include <v8.h>
 
-In this function you can create new javascript objects and attach them to
-+target+. Here is a very simple module:
+using namespace v8;
 
------------------------------------------------------
 extern "C" void
 init (Handle<Object> target) 
 {
@@ -1330,7 +1310,39 @@ init (Handle<Object> target)
 }
 -----------------------------------------------------
 
-Further documentation will come soon. For now see the source code of
-http://github.com/ry/node_postgres[node_postgres].
+This source code needs to be built into +hello.node+, the binary Addon. To
+do this we create a file called +wscript+ which is python code and looks
+like this:
+-----------------------------------------------------
+srcdir = '.'
+blddir = 'build'
+VERSION = '0.0.1'
+
+def set_options(opt):
+  opt.tool_options('compiler_cxx')
+
+def configure(conf):
+  conf.check_tool('compiler_cxx')
+  conf.check_tool('node_addon')
+  conf.check_node_headers()
+
+def build(bld):
+  obj = bld.new_task_gen('cxx', 'shlib', 'node_addon')
+  obj.target = 'hello'
+  obj.source = "hello.cc"
+-----------------------------------------------------
+Running +node-waf configure build+ will create a file
++build/default/hello.node+ which is our Addon.
+
++node-waf+ is just http://code.google.com/p/waf/[WAF], the python-based build system. +node-waf+ is
+provided for the ease of users.
+
+All Node addons must export a function called +init+ with this signature:
+-----------------------------------------------------
+extern "C" void init (Handle<Object> target) 
+-----------------------------------------------------
+
+For the moment, that is all the documentation on addons. Please see
+http://github.com/ry/node_postgres[node_postgres] for a real example.
 
 // vim: set syntax=asciidoc: