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