First try at explaining how to create a self-contained extension

1 files changed, 106 insertions, 0 deletions

diff --git a/README.SELF-CONTAINED-EXTENSIONS b/README.SELF-CONTAINED-EXTENSIONS
new file mode 100644
index 0000000000..5e7b3763d6
--- /dev/null
+++ b/README.SELF-CONTAINED-EXTENSIONS
@@ -0,0 +1,106 @@
+HOW TO CREATE A SELF-CONTAINED PHP EXTENSION
+$Id$
+
+  A self-contained extension can be distributed independently of
+  the PHP source. To create such an extension, three things are
+  required:
+
+  - Makefile template (Makefile.in)
+  - Configuration file (config.m4)
+  - Source code for your module
+
+  We will describe now how to create these and how to put things
+  together.
+
+
+SPECIFYING THE EXTENSION
+
+  Our demo extension is called "foobar".
+
+  It consists of two source files "foo.c" and "bar.c"
+  (and any arbitrary amount of header files, but that is not
+  important here).
+  
+  The demo extension does not reference any external 
+  libraries (that is important, because the user does not
+  need to specify anything).
+
+
+CREATING THE MAKEFILE TEMPLATE 
+  
+  The Makefile Template (Makefile.in) contains three lines:
+
+------------------------------------------------------------------------------
+LTLIBRARY_SHARED_NAME = foobar.la
+LTLIBRARY_SOURCES     = foo.c bar.c
+
+include $(top_srcdir)/build/rules.mk
+------------------------------------------------------------------------------
+
+  LTLIBRARY_SHARED_NAME specifies the name of the extension.
+  It must be of the form `ext-name.la'.
+
+  LTLIBRARY_SOURCES specifies the names of the sources files. You can
+  name an arbitrary number of source files here.
+
+  The final include directive includes the build rules (you usually
+  don't need to care about what happens there). rules.mk and other
+  files are installed by phpize which we will cover later.
+
+
+CREATING THE M4 CONFIGURATION FILE
+
+  The m4 configuration can perform additional checks. For a 
+  self-contained extension, you do not need more than a few
+  macro calls.
+
+------------------------------------------------------------------------------
+PHP_ARG_ENABLE(foobar,whether to enable foobar,
+[  --enable-foobar            Enable foobar])
+
+PHP_EXTENSION(foobar, $ext_shared)
+------------------------------------------------------------------------------
+
+  PHP_ARG_ENABLE will automatically set the correct variables, so
+  that the extension will be enabled by PHP_EXTENSION in shared mode.
+
+
+CREATING SOURCE FILES
+
+  [You are currently alone here. There are a lot of existing modules,
+   use a simply module as a starting point and add your own code.]
+
+
+CREATING THE SELF-CONTAINED EXTENSION
+
+  Put Makefile.in, config.m4 and the source files into one directory.
+  Then run phpize (this is installed during make install by PHP 4.0).
+  For example, if you configured PHP with --prefix=/php, you would run
+
+     $ /php/bin/phpize
+
+  This will automatically copy the necessary build files and create
+  configure from your config.m4.
+
+  And that's it. You now have a self-contained extension.
+
+  It can be installed by running:
+
+  $ ./configure [--with-php-config=/path/to/php-config]
+  $ make install
+
+CONVERTING AN EXISTING EXTENSION
+
+  If you want to distribute an extension from the PHP repository, copy
+  all files from the extension's directory to a new directory and
+  run phpize as described above. That's all!
+
+  For example:
+
+     $ dir=/tmp/new_moduke
+     $ cd php4/ext/mysql
+     $ mkdir $dir
+     $ cp -rp * $dir
+     $ cd $dir
+     $ phpize
+