Skip to content
Newer
Older
100644 157 lines (101 sloc) 4.63 KB
dd497bd First try at explaining how to create a self-contained extension
Sascha Schumann authored May 2, 2000
1 $Id$
bf58db4 Verbose "give the reader a quick success" tutorial
Sascha Schumann authored May 2, 2000
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 May 2, 2000
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 May 2, 2000
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 May 2, 2000
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 Jun 9, 2000
72 include $(top_srcdir)/build/dynlib.mk
dd497bd First try at explaining how to create a self-contained extension
Sascha Schumann authored May 2, 2000
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 Jun 8, 2000
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 May 2, 2000
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 Jun 8, 2000
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 May 2, 2000
107
108 CREATING SOURCE FILES
109
110 [You are currently alone here. There are a lot of existing modules,
111 use a simply module as a starting point and add your own code.]
112
113
114 CREATING THE SELF-CONTAINED EXTENSION
115
116 Put Makefile.in, config.m4 and the source files into one directory.
117 Then run phpize (this is installed during make install by PHP 4.0).
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
bf58db4 Verbose "give the reader a quick success" tutorial
Sascha Schumann authored May 2, 2000
127 INSTALLING A SELF-CONTAINED EXTENSION
dd497bd First try at explaining how to create a self-contained extension
Sascha Schumann authored May 2, 2000
128
bf58db4 Verbose "give the reader a quick success" tutorial
Sascha Schumann authored May 2, 2000
129 An extension can be installed by running:
dd497bd First try at explaining how to create a self-contained extension
Sascha Schumann authored May 2, 2000
130
bf58db4 Verbose "give the reader a quick success" tutorial
Sascha Schumann authored May 2, 2000
131 $ ./configure \
132 [--with-php-config=/path/to/php-config]
133 $ make install
8a3edf2 Add section about adding shared module support to an existing module.
Sascha Schumann authored May 22, 2000
134
135 ADDING SHARED MODULE SUPPORT TO A MODULE
136
137 In order to be useful, a self-contained extension must be loadable
7b89a00 Fix typo
Sascha Schumann authored Jun 10, 2000
138 as a shared module. I will explain now how you can add shared module
139 support to an existing module called foo.
8a3edf2 Add section about adding shared module support to an existing module.
Sascha Schumann authored May 22, 2000
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_EXTENSION(foo, $ext_shared) to enable
146 building the extension.
147
148 3. Add the following line to Makefile.in:
149
150 LTLIBRARY_SHARED_NAME = foo.la
151
152 4. Add the following lines to your C source file:
153
49b2166 Use new syntax
Sascha Schumann authored May 23, 2000
154 #ifdef COMPILE_DL_FOO
8a3edf2 Add section about adding shared module support to an existing module.
Sascha Schumann authored May 22, 2000
155 ZEND_GET_MODULE(foo)
156 #endif
Something went wrong with that request. Please try again.