Annotation of embedaddon/php/README.SELF-CONTAINED-EXTENSIONS, revision 1.1.1.3
1.1.1.2 misho 1: $Id$
1.1 misho 2: =============================================================================
3:
4: HOW TO CREATE A SELF-CONTAINED PHP EXTENSION
5:
6: A self-contained extension can be distributed independently of
7: the PHP source. To create such an extension, two things are
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:
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/
29:
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
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:
89: if test "$PHP_FOOBAR" != "no"; then
90: PHP_NEW_EXTENSION(foobar, foo.c bar.c, $ext_shared)
91: fi
92: ------------------------------------------------------------------------------
93:
94: PHP_ARG_ENABLE will automatically set the correct variables, so
95: that the extension will be enabled by PHP_NEW_EXTENSION in shared mode.
96:
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:
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.
104:
105: CREATING SOURCE FILES
106:
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.
114:
115:
116: CREATING THE SELF-CONTAINED EXTENSION
117:
118: Put config.m4 and the source files into one directory. Then, run phpize
119: (this is installed during make install by PHP 4.0).
120:
121: For example, if you configured PHP with --prefix=/php, you would run
122:
123: $ /php/bin/phpize
124:
125: This will automatically copy the necessary build files and create
126: configure from your config.m4.
127:
128: And that's it. You now have a self-contained extension.
129:
130: INSTALLING A SELF-CONTAINED EXTENSION
131:
132: An extension can be installed by running:
133:
134: $ ./configure \
135: [--with-php-config=/path/to/php-config]
136: $ make install
137:
138: ADDING SHARED MODULE SUPPORT TO A MODULE
139:
140: In order to be useful, a self-contained extension must be loadable
141: as a shared module. I will explain now how you can add shared module
142: support to an existing module called foo.
143:
144: 1. In config.m4, use PHP_ARG_WITH/PHP_ARG_ENABLE. Then you will
145: automatically be able to use --with-foo=shared[,..] or
146: --enable-foo=shared[,..].
147:
148: 2. In config.m4, use PHP_NEW_EXTENSION(foo,.., $ext_shared) to enable
149: building the extension.
150:
151: 3. Add the following lines to your C source file:
152:
153: #ifdef COMPILE_DL_FOO
154: ZEND_GET_MODULE(foo)
155: #endif
1.1.1.3 ! misho 156:
! 157: PECL SITE CONFORMITY
! 158:
! 159: If you plan to release an extension to the PECL website, there are several
! 160: points to be regarded.
! 161:
! 162: 1. Add LICENSE or COPYING to the package.xml
! 163:
! 164: 2. The following should be defined in one of the extension header files
! 165:
! 166: #define PHP_FOO_VERSION "1.2.3"
! 167:
! 168: This macros has to be used within your foo_module_entry to indicate the
! 169: extension version.
! 170:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to README.SELF-CONTAINED-EXTENSIONS CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / php