Return to README.SELF-CONTAINED-EXTENSIONS CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / php

Annotation of embedaddon/php/README.SELF-CONTAINED-EXTENSIONS, revision 1.1.1.2

1.1.1.2 ! misho       1: $Id$
1.1       misho       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