Imported from /home/lorry/working-area/delta_php2/php-5.4.13.tar.bz2.HEADphp-5.4.13master

1 files changed, 155 insertions, 0 deletions

diff --git a/README.SELF-CONTAINED-EXTENSIONS b/README.SELF-CONTAINED-EXTENSIONS
new file mode 100644
index 0000000..e6a3753
--- /dev/null
+++ b/README.SELF-CONTAINED-EXTENSIONS
@@ -0,0 +1,155 @@
+$Id$
+=============================================================================
+
+HOW TO CREATE A SELF-CONTAINED PHP EXTENSION
+
+  A self-contained extension can be distributed independently of
+  the PHP source. To create such an extension, two things are
+  required:
+
+  - Configuration file (config.m4)
+  - Source code for your module
+
+  We will describe now how to create these and how to put things
+  together.
+
+PREPARING YOUR SYSTEM
+
+  While the result will run on any system, a developer's setup needs these
+  tools:
+
+    GNU autoconf
+    GNU automake
+    GNU libtool
+    GNU m4
+
+  All of these are available from 
+
+    ftp://ftp.gnu.org/pub/gnu/
+
+CONVERTING AN EXISTING EXTENSION
+
+  Just to show you how easy it is to create a self-contained
+  extension, we will convert an embedded extension into a
+  self-contained one. Install PHP and execute the following
+  commands.
+  
+     $ mkdir /tmp/newext
+     $ cd /tmp/newext
+
+  You now have an empty directory. We will copy the files from
+  the mysql extension:
+
+     $ cp -rp php-4.0.X/ext/mysql/* .
+
+  It is time to finish the module. Run:
+
+     $ phpize
+
+  You can now ship the contents of the directory - the extension
+  can live completely on its own.
+
+  The user instructions boil down to
+
+     $ ./configure \
+            [--with-php-config=/path/to/php-config] \
+            [--with-mysql=MYSQL-DIR]
+     $ make install
+
+  The MySQL module will either use the embedded MySQL client 
+  library or the MySQL installation in MYSQL-DIR.
+
+
+DEFINING THE NEW 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).
+
+
+  LTLIBRARY_SOURCES specifies the names of the sources files. You can
+  name an arbitrary number of source files here.
+
+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])
+
+if test "$PHP_FOOBAR" != "no"; then
+  PHP_NEW_EXTENSION(foobar, foo.c bar.c, $ext_shared)
+fi
+------------------------------------------------------------------------------
+
+  PHP_ARG_ENABLE will automatically set the correct variables, so
+  that the extension will be enabled by PHP_NEW_EXTENSION in shared mode.
+
+  The first argument of PHP_NEW_EXTENSION describes the name of the
+  extension.  The second names the source-code files.  The third passes
+  $ext_shared which is set by PHP_ARG_ENABLE/WITH to PHP_NEW_EXTENSION.
+  
+  Please use always PHP_ARG_ENABLE or PHP_ARG_WITH. Even if you do not
+  plan to distribute your module with PHP, these facilities allow you
+  to integrate your module easily into the main PHP module framework.
+
+CREATING SOURCE FILES
+
+  ext_skel can be of great help when creating the common code for all modules
+  in PHP for you and also writing basic function definitions and C code for
+  handling arguments passed to your functions. See README.EXT_SKEL for further
+  information.
+
+  As for the rest, you are currently alone here. There are a lot of existing
+  modules, use a simple module as a starting point and add your own code.
+
+
+CREATING THE SELF-CONTAINED EXTENSION
+
+  Put 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.
+
+INSTALLING A SELF-CONTAINED EXTENSION
+
+  An extension can be installed by running:
+
+     $ ./configure \
+            [--with-php-config=/path/to/php-config]
+     $ make install
+
+ADDING SHARED MODULE SUPPORT TO A MODULE
+
+  In order to be useful, a self-contained extension must be loadable
+  as a shared module. I will explain now how you can add shared module 
+  support to an existing module called foo.
+
+  1. In config.m4, use PHP_ARG_WITH/PHP_ARG_ENABLE. Then you will
+     automatically be able to use --with-foo=shared[,..] or
+     --enable-foo=shared[,..].
+
+  2. In config.m4, use PHP_NEW_EXTENSION(foo,.., $ext_shared) to enable
+     building the extension.
+
+  3. Add the following lines to your C source file:
+
+        #ifdef COMPILE_DL_FOO
+        ZEND_GET_MODULE(foo)
+        #endif