Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
tag: php-4.0.4RC4
Fetching contributors…

Cannot retrieve contributors at this time

file 174 lines (114 sloc) 5.241 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174
$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, 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.

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).


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/dynlib.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])

if test "$PHP_FOOBAR" != "no"; then
  PHP_EXTENSION(foobar, $ext_shared)
fi
------------------------------------------------------------------------------

  PHP_ARG_ENABLE will automatically set the correct variables, so
  that the extension will be enabled by PHP_EXTENSION in shared mode.

  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 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.

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_EXTENSION(foo, $ext_shared) to enable
     building the extension.

  3. Add the following line to Makefile.in:

        LTLIBRARY_SHARED_NAME = foo.la

  4. Add the following lines to your C source file:

        #ifdef COMPILE_DL_FOO
        ZEND_GET_MODULE(foo)
        #endif
Something went wrong with that request. Please try again.