Return to README.SELF-CONTAINED-EXTENSIONS CVS log

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

php 5.4.29

    1: $Id: README.SELF-CONTAINED-EXTENSIONS,v 1.1.1.3 2014/06/15 20:03:41 misho Exp $
    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
  156: 
  157: PECL SITE CONFORMITY
  158: 
  159:   If you plan to release an extension to the PECL website, there are several
  160:   points to be regarded.
  161: 
  162:  1. Add LICENSE or COPYING to the package.xml
  163: 
  164:  2. The following should be defined in one of the extension header files
  165: 
  166:         #define PHP_FOO_VERSION "1.2.3"
  167: 
  168:     This macros has to be used within your foo_module_entry to indicate the
  169:     extension version.
  170: