mirror of
https://github.com/php/php-src.git
synced 2024-09-21 18:07:23 +00:00
162 lines
4.9 KiB
Plaintext
162 lines
4.9 KiB
Plaintext
$Id$
|
|
=============================================================================
|
|
|
|
HOW TO CREATE A SELF-CONTAINED PHP EXTENSION
|
|
|
|
A self-contained extension can be distributed independently of
|
|
the PHP source. To create such an extension, three things are
|
|
required:
|
|
|
|
- Makefile template (Makefile.in)
|
|
- Configuration file (config.m4)
|
|
- Source code for your module
|
|
|
|
We will describe now how to create these and how to put things
|
|
together.
|
|
|
|
|
|
CONVERTING AN EXISTING EXTENSION
|
|
|
|
Just to show you how easy it is to create a self-contained
|
|
extension, we will convert an embedded extension into a
|
|
self-contained one. Install PHP and execute the following
|
|
commands.
|
|
|
|
$ mkdir /tmp/newext
|
|
$ cd /tmp/newext
|
|
|
|
You now have an empty directory. We will copy the files from
|
|
the mysql extension:
|
|
|
|
$ cp -rp php-4.0.X/ext/mysql/* .
|
|
|
|
It is time to finish the module. Run:
|
|
|
|
$ phpize
|
|
|
|
You can now ship the contents of the directory - the extension
|
|
can live completely on its own.
|
|
|
|
The user instructions boil down to
|
|
|
|
$ ./configure \
|
|
[--with-php-config=/path/to/php-config] \
|
|
[--with-mysql=MYSQL-DIR]
|
|
$ make install
|
|
|
|
The MySQL module will either use the embedded MySQL client
|
|
library or the MySQL installation in MYSQL-DIR.
|
|
|
|
|
|
DEFINING THE NEW EXTENSION
|
|
|
|
Our demo extension is called "foobar".
|
|
|
|
It consists of two source files "foo.c" and "bar.c"
|
|
(and any arbitrary amount of header files, but that is not
|
|
important here).
|
|
|
|
The demo extension does not reference any external
|
|
libraries (that is important, because the user does not
|
|
need to specify anything).
|
|
|
|
|
|
CREATING THE MAKEFILE TEMPLATE
|
|
|
|
The Makefile Template (Makefile.in) contains three lines:
|
|
|
|
------------------------------------------------------------------------------
|
|
LTLIBRARY_SHARED_NAME = foobar.la
|
|
LTLIBRARY_SOURCES = foo.c bar.c
|
|
|
|
include $(top_srcdir)/build/dynlib.mk
|
|
------------------------------------------------------------------------------
|
|
|
|
LTLIBRARY_SHARED_NAME specifies the name of the extension.
|
|
It must be of the form `ext-name.la'.
|
|
|
|
LTLIBRARY_SOURCES specifies the names of the sources files. You can
|
|
name an arbitrary number of source files here.
|
|
|
|
The final include directive includes the build rules (you usually
|
|
don't need to care about what happens there). rules.mk and other
|
|
files are installed by phpize which we will cover later.
|
|
|
|
|
|
CREATING THE M4 CONFIGURATION FILE
|
|
|
|
The m4 configuration can perform additional checks. For a
|
|
self-contained extension, you do not need more than a few
|
|
macro calls.
|
|
|
|
------------------------------------------------------------------------------
|
|
PHP_ARG_ENABLE(foobar,whether to enable foobar,
|
|
[ --enable-foobar Enable foobar])
|
|
|
|
if test "$PHP_FOOBAR" != "no"; then
|
|
PHP_EXTENSION(foobar, $ext_shared)
|
|
fi
|
|
------------------------------------------------------------------------------
|
|
|
|
PHP_ARG_ENABLE will automatically set the correct variables, so
|
|
that the extension will be enabled by PHP_EXTENSION in shared mode.
|
|
|
|
Please use always PHP_ARG_ENABLE or PHP_ARG_WITH. Even if you do not
|
|
plan to distribute your module with PHP, these facilities allow you
|
|
to integrate your module easily into the main PHP module framework.
|
|
|
|
CREATING SOURCE FILES
|
|
|
|
ext_skel can be of great help when creating the common code for all modules
|
|
in PHP for you and also writing basic function definitions and C code for
|
|
handling arguments passed to your functions. See README.EXT_SKEL for further
|
|
information.
|
|
|
|
As for the rest, you are currently alone here. There are a lot of existing
|
|
modules, use a simple module as a starting point and add your own code.
|
|
|
|
|
|
CREATING THE SELF-CONTAINED EXTENSION
|
|
|
|
Put Makefile.in, config.m4 and the source files into one directory.
|
|
Then run phpize (this is installed during make install by PHP 4.0).
|
|
For example, if you configured PHP with --prefix=/php, you would run
|
|
|
|
$ /php/bin/phpize
|
|
|
|
This will automatically copy the necessary build files and create
|
|
configure from your config.m4.
|
|
|
|
And that's it. You now have a self-contained extension.
|
|
|
|
INSTALLING A SELF-CONTAINED EXTENSION
|
|
|
|
An extension can be installed by running:
|
|
|
|
$ ./configure \
|
|
[--with-php-config=/path/to/php-config]
|
|
$ make install
|
|
|
|
ADDING SHARED MODULE SUPPORT TO A MODULE
|
|
|
|
In order to be useful, a self-contained extension must be loadable
|
|
as a shared module. I will explain now how you can add shared module
|
|
support to an existing module called foo.
|
|
|
|
1. In config.m4, use PHP_ARG_WITH/PHP_ARG_ENABLE. Then you will
|
|
automatically be able to use --with-foo=shared or
|
|
--enable-foo=shared.
|
|
|
|
2. In config.m4, use PHP_EXTENSION(foo, $ext_shared) to enable
|
|
building the extension.
|
|
|
|
3. Add the following line to Makefile.in:
|
|
|
|
LTLIBRARY_SHARED_NAME = foo.la
|
|
|
|
4. Add the following lines to your C source file:
|
|
|
|
#ifdef COMPILE_DL_FOO
|
|
ZEND_GET_MODULE(foo)
|
|
#endif
|