Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 162 lines (105 sloc) 5.004 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
7 the PHP source. To create such an extension, three things are
8 required:
9
10 - Makefile template (Makefile.in)
11 - Configuration file (config.m4)
12 - Source code for your module
13
14 We will describe now how to create these and how to put things
15 together.
16
17
bf58db4 Verbose "give the reader a quick success" tutorial
Sascha Schumann authored
18 CONVERTING AN EXISTING EXTENSION
19
20 Just to show you how easy it is to create a self-contained
21 extension, we will convert an embedded extension into a
22 self-contained one. Install PHP and execute the following
23 commands.
24
25 $ mkdir /tmp/newext
26 $ cd /tmp/newext
27
28 You now have an empty directory. We will copy the files from
29 the mysql extension:
30
31 $ cp -rp php-4.0.X/ext/mysql/* .
32
33 It is time to finish the module. Run:
34
35 $ phpize
36
37 You can now ship the contents of the directory - the extension
38 can live completely on its own.
39
40 The user instructions boil down to
41
42 $ ./configure \
43 [--with-php-config=/path/to/php-config] \
44 [--with-mysql=MYSQL-DIR]
45 $ make install
46
47 The MySQL module will either use the embedded MySQL client
48 library or the MySQL installation in MYSQL-DIR.
49
50
51 DEFINING THE NEW EXTENSION
dd497bd First try at explaining how to create a self-contained extension
Sascha Schumann authored
52
53 Our demo extension is called "foobar".
54
55 It consists of two source files "foo.c" and "bar.c"
56 (and any arbitrary amount of header files, but that is not
57 important here).
58
59 The demo extension does not reference any external
60 libraries (that is important, because the user does not
61 need to specify anything).
62
63
64 CREATING THE MAKEFILE TEMPLATE
65
66 The Makefile Template (Makefile.in) contains three lines:
67
68 ------------------------------------------------------------------------------
69 LTLIBRARY_SHARED_NAME = foobar.la
70 LTLIBRARY_SOURCES = foo.c bar.c
71
fb330f7 You need to include dynlib.mk in Makefile.in.
Sascha Schumann authored
72 include $(top_srcdir)/build/dynlib.mk
dd497bd First try at explaining how to create a self-contained extension
Sascha Schumann authored
73 ------------------------------------------------------------------------------
74
75 LTLIBRARY_SHARED_NAME specifies the name of the extension.
76 It must be of the form `ext-name.la'.
77
78 LTLIBRARY_SOURCES specifies the names of the sources files. You can
79 name an arbitrary number of source files here.
80
81 The final include directive includes the build rules (you usually
82 don't need to care about what happens there). rules.mk and other
83 files are installed by phpize which we will cover later.
84
85
86 CREATING THE M4 CONFIGURATION FILE
87
88 The m4 configuration can perform additional checks. For a
89 self-contained extension, you do not need more than a few
90 macro calls.
91
92 ------------------------------------------------------------------------------
93 PHP_ARG_ENABLE(foobar,whether to enable foobar,
94 [ --enable-foobar Enable foobar])
95
471a07f Add note about using PHP_ARG_WITH/ENABLE
Sascha Schumann authored
96 if test "$PHP_FOOBAR" != "no"; then
97 PHP_EXTENSION(foobar, $ext_shared)
98 fi
dd497bd First try at explaining how to create a self-contained extension
Sascha Schumann authored
99 ------------------------------------------------------------------------------
100
101 PHP_ARG_ENABLE will automatically set the correct variables, so
102 that the extension will be enabled by PHP_EXTENSION in shared mode.
103
471a07f Add note about using PHP_ARG_WITH/ENABLE
Sascha Schumann authored
104 Please use always PHP_ARG_ENABLE or PHP_ARG_WITH. Even if you do not
105 plan to distribute your module with PHP, these facilities allow you
106 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
107
108 CREATING SOURCE FILES
109
d09ec32 - Add some documentation for ext_skel and a note about it's existence.
Jouni Ahto authored
110 ext_skel can be of great help when creating the common code for all modules
111 in PHP for you and also writing basic function definitions and C code for
112 handling arguments passed to your functions. See README.EXT_SKEL for further
113 information.
114
115 As for the rest, you are currently alone here. There are a lot of existing
116 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
117
118
119 CREATING THE SELF-CONTAINED EXTENSION
120
121 Put Makefile.in, config.m4 and the source files into one directory.
122 Then run phpize (this is installed during make install by PHP 4.0).
123 For example, if you configured PHP with --prefix=/php, you would run
124
125 $ /php/bin/phpize
126
127 This will automatically copy the necessary build files and create
128 configure from your config.m4.
129
130 And that's it. You now have a self-contained extension.
131
bf58db4 Verbose "give the reader a quick success" tutorial
Sascha Schumann authored
132 INSTALLING A SELF-CONTAINED EXTENSION
dd497bd First try at explaining how to create a self-contained extension
Sascha Schumann authored
133
bf58db4 Verbose "give the reader a quick success" tutorial
Sascha Schumann authored
134 An extension can be installed by running:
dd497bd First try at explaining how to create a self-contained extension
Sascha Schumann authored
135
bf58db4 Verbose "give the reader a quick success" tutorial
Sascha Schumann authored
136 $ ./configure \
137 [--with-php-config=/path/to/php-config]
138 $ make install
8a3edf2 Add section about adding shared module support to an existing module.
Sascha Schumann authored
139
140 ADDING SHARED MODULE SUPPORT TO A MODULE
141
142 In order to be useful, a self-contained extension must be loadable
7b89a00 Fix typo
Sascha Schumann authored
143 as a shared module. I will explain now how you can add shared module
144 support to an existing module called foo.
8a3edf2 Add section about adding shared module support to an existing module.
Sascha Schumann authored
145
146 1. In config.m4, use PHP_ARG_WITH/PHP_ARG_ENABLE. Then you will
147 automatically be able to use --with-foo=shared or
148 --enable-foo=shared.
149
150 2. In config.m4, use PHP_EXTENSION(foo, $ext_shared) to enable
151 building the extension.
152
153 3. Add the following line to Makefile.in:
154
155 LTLIBRARY_SHARED_NAME = foo.la
156
157 4. Add the following lines to your C source file:
158
49b2166 Use new syntax
Sascha Schumann authored
159 #ifdef COMPILE_DL_FOO
8a3edf2 Add section about adding shared module support to an existing module.
Sascha Schumann authored
160 ZEND_GET_MODULE(foo)
161 #endif
Something went wrong with that request. Please try again.