Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 155 lines (102 sloc) 4.703 kb
dd497bd First try at explaining how to create a self-contained extension
Sascha Schumann authored
1 $Id$
bf58db4 Verbose "give the reader a quick success" tutorial
Sascha Schumann authored
2 =============================================================================
3
4 HOW TO CREATE A SELF-CONTAINED PHP EXTENSION
dd497bd First try at explaining how to create a self-contained extension
Sascha Schumann authored
5
6 A self-contained extension can be distributed independently of
2d8027e Fix some verbage.
Sean Bright authored
7 the PHP source. To create such an extension, two things are
dd497bd First try at explaining how to create a self-contained extension
Sascha Schumann authored
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
04182c1 Add note about software requirements
Sascha Schumann authored
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/
dd497bd First try at explaining how to create a self-contained extension
Sascha Schumann authored
29
bf58db4 Verbose "give the reader a quick success" tutorial
Sascha Schumann authored
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
dd497bd First try at explaining how to create a self-contained extension
Sascha Schumann authored
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
471a07f Add note about using PHP_ARG_WITH/ENABLE
Sascha Schumann authored
89 if test "$PHP_FOOBAR" != "no"; then
9d9d39a Please welcome the new build system.
Sascha Schumann authored
90 PHP_NEW_EXTENSION(foobar, foo.c bar.c, $ext_shared)
471a07f Add note about using PHP_ARG_WITH/ENABLE
Sascha Schumann authored
91 fi
dd497bd First try at explaining how to create a self-contained extension
Sascha Schumann authored
92 ------------------------------------------------------------------------------
93
94 PHP_ARG_ENABLE will automatically set the correct variables, so
9d9d39a Please welcome the new build system.
Sascha Schumann authored
95 that the extension will be enabled by PHP_NEW_EXTENSION in shared mode.
dd497bd First try at explaining how to create a self-contained extension
Sascha Schumann authored
96
9d9d39a Please welcome the new build system.
Sascha Schumann authored
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
471a07f Add note about using PHP_ARG_WITH/ENABLE
Sascha Schumann authored
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.
dd497bd First try at explaining how to create a self-contained extension
Sascha Schumann authored
104
105 CREATING SOURCE FILES
106
d09ec32 - Add some documentation for ext_skel and a note about it's existence.
Jouni Ahto authored
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.
dd497bd First try at explaining how to create a self-contained extension
Sascha Schumann authored
114
115
116 CREATING THE SELF-CONTAINED EXTENSION
117
9d9d39a Please welcome the new build system.
Sascha Schumann authored
118 Put config.m4 and the source files into one directory. Afterwards,
119 run phpize (this is installed during make install by PHP 4.0).
dd497bd First try at explaining how to create a self-contained extension
Sascha Schumann authored
120 For example, if you configured PHP with --prefix=/php, you would run
121
122 $ /php/bin/phpize
123
124 This will automatically copy the necessary build files and create
125 configure from your config.m4.
126
127 And that's it. You now have a self-contained extension.
128
bf58db4 Verbose "give the reader a quick success" tutorial
Sascha Schumann authored
129 INSTALLING A SELF-CONTAINED EXTENSION
dd497bd First try at explaining how to create a self-contained extension
Sascha Schumann authored
130
bf58db4 Verbose "give the reader a quick success" tutorial
Sascha Schumann authored
131 An extension can be installed by running:
dd497bd First try at explaining how to create a self-contained extension
Sascha Schumann authored
132
bf58db4 Verbose "give the reader a quick success" tutorial
Sascha Schumann authored
133 $ ./configure \
134 [--with-php-config=/path/to/php-config]
135 $ make install
8a3edf2 Add section about adding shared module support to an existing module.
Sascha Schumann authored
136
137 ADDING SHARED MODULE SUPPORT TO A MODULE
138
139 In order to be useful, a self-contained extension must be loadable
7b89a00 Fix typo
Sascha Schumann authored
140 as a shared module. I will explain now how you can add shared module
141 support to an existing module called foo.
8a3edf2 Add section about adding shared module support to an existing module.
Sascha Schumann authored
142
143 1. In config.m4, use PHP_ARG_WITH/PHP_ARG_ENABLE. Then you will
9d9d39a Please welcome the new build system.
Sascha Schumann authored
144 automatically be able to use --with-foo=shared[,..] or
145 --enable-foo=shared[,..].
8a3edf2 Add section about adding shared module support to an existing module.
Sascha Schumann authored
146
9d9d39a Please welcome the new build system.
Sascha Schumann authored
147 2. In config.m4, use PHP_NEW_EXTENSION(foo,.., $ext_shared) to enable
8a3edf2 Add section about adding shared module support to an existing module.
Sascha Schumann authored
148 building the extension.
149
9d9d39a Please welcome the new build system.
Sascha Schumann authored
150 3. Add the following lines to your C source file:
8a3edf2 Add section about adding shared module support to an existing module.
Sascha Schumann authored
151
49b2166 Use new syntax
Sascha Schumann authored
152 #ifdef COMPILE_DL_FOO
8a3edf2 Add section about adding shared module support to an existing module.
Sascha Schumann authored
153 ZEND_GET_MODULE(foo)
154 #endif
Something went wrong with that request. Please try again.