release/src/router/php/README.SELF-CONTAINED-EXTENSIONS

   1 $Id$
   2 =============================================================================
   3
   4 HOW TO CREATE A SELF-CONTAINED PHP EXTENSION
   5
   6   A self-contained extension can be distributed independently of
   7   the PHP source. To create such an extension, two things are
   8   required:
   9
  10   - Configuration file (config.m4)
  11   - Source code for your module
  12
  13   We will describe now how to create these and how to put things
  14   together.
  15
  16 PREPARING YOUR SYSTEM
  17
  18   While the result will run on any system, a developer's setup needs these
  19   tools:
  20
  21     GNU autoconf
  22     GNU automake
  23     GNU libtool
  24     GNU m4
  25
  26   All of these are available from
  27
  28     ftp://ftp.gnu.org/pub/gnu/
  29
  30 CONVERTING AN EXISTING EXTENSION
  31
  32   Just to show you how easy it is to create a self-contained
  33   extension, we will convert an embedded extension into a
  34   self-contained one. Install PHP and execute the following
  35   commands.
  36
  37      $ mkdir /tmp/newext
  38      $ cd /tmp/newext
  39
  40   You now have an empty directory. We will copy the files from
  41   the mysql extension:
  42
  43      $ cp -rp php-4.0.X/ext/mysql/* .
  44
  45   It is time to finish the module. Run:
  46
  47      $ phpize
  48
  49   You can now ship the contents of the directory - the extension
  50   can live completely on its own.
  51
  52   The user instructions boil down to
  53
  54      $ ./configure \
  55             [--with-php-config=/path/to/php-config] \
  56             [--with-mysql=MYSQL-DIR]
  57      $ make install
  58
  59   The MySQL module will either use the embedded MySQL client
  60   library or the MySQL installation in MYSQL-DIR.
  61
  62
  63 DEFINING THE NEW EXTENSION
  64
  65   Our demo extension is called "foobar".
  66
  67   It consists of two source files "foo.c" and "bar.c"
  68   (and any arbitrary amount of header files, but that is not
  69   important here).
  70
  71   The demo extension does not reference any external
  72   libraries (that is important, because the user does not
  73   need to specify anything).
  74
  75
  76   LTLIBRARY_SOURCES specifies the names of the sources files. You can
  77   name an arbitrary number of source files here.
  78
  79 CREATING THE M4 CONFIGURATION FILE
  80
  81   The m4 configuration can perform additional checks. For a
  82   self-contained extension, you do not need more than a few
  83   macro calls.
  84
  85 ------------------------------------------------------------------------------
  86 PHP_ARG_ENABLE(foobar,whether to enable foobar,
  87 [  --enable-foobar            Enable foobar])
  88
  89 if test "$PHP_FOOBAR" != "no"; then
  90   PHP_NEW_EXTENSION(foobar, foo.c bar.c, $ext_shared)
  91 fi
  92 ------------------------------------------------------------------------------
  93
  94   PHP_ARG_ENABLE will automatically set the correct variables, so
  95   that the extension will be enabled by PHP_NEW_EXTENSION in shared mode.
  96
  97   The first argument of PHP_NEW_EXTENSION describes the name of the
  98   extension.  The second names the source-code files.  The third passes
  99   $ext_shared which is set by PHP_ARG_ENABLE/WITH to PHP_NEW_EXTENSION.
 100
 101   Please use always PHP_ARG_ENABLE or PHP_ARG_WITH. Even if you do not
 102   plan to distribute your module with PHP, these facilities allow you
 103   to integrate your module easily into the main PHP module framework.
 104
 105 CREATING SOURCE FILES
 106
 107   ext_skel can be of great help when creating the common code for all modules
 108   in PHP for you and also writing basic function definitions and C code for
 109   handling arguments passed to your functions. See README.EXT_SKEL for further
 110   information.
 111
 112   As for the rest, you are currently alone here. There are a lot of existing
 113   modules, use a simple module as a starting point and add your own code.
 114
 115
 116 CREATING THE SELF-CONTAINED EXTENSION
 117
 118   Put config.m4 and the source files into one directory. Then, run phpize
 119   (this is installed during make install by PHP 4.0).
 120
 121   For example, if you configured PHP with --prefix=/php, you would run
 122
 123      $ /php/bin/phpize
 124
 125   This will automatically copy the necessary build files and create
 126   configure from your config.m4.
 127
 128   And that's it. You now have a self-contained extension.
 129
 130 INSTALLING A SELF-CONTAINED EXTENSION
 131
 132   An extension can be installed by running:
 133
 134      $ ./configure \
 135             [--with-php-config=/path/to/php-config]
 136      $ make install
 137
 138 ADDING SHARED MODULE SUPPORT TO A MODULE
 139
 140   In order to be useful, a self-contained extension must be loadable
 141   as a shared module. I will explain now how you can add shared module
 142   support to an existing module called foo.
 143
 144   1. In config.m4, use PHP_ARG_WITH/PHP_ARG_ENABLE. Then you will
 145      automatically be able to use --with-foo=shared[,..] or
 146      --enable-foo=shared[,..].
 147
 148   2. In config.m4, use PHP_NEW_EXTENSION(foo,.., $ext_shared) to enable
 149      building the extension.
 150
 151   3. Add the following lines to your C source file:
 152
 153         #ifdef COMPILE_DL_FOO
 154         ZEND_GET_MODULE(foo)
 155         #endif