mirror of
https://github.com/php/php-src.git
synced 2024-12-01 13:54:10 +08:00
8d3f8ca12a
The $Id$ keywords were used in Subversion where they can be substituted with filename, last revision number change, last changed date, and last user who changed it. In Git this functionality is different and can be done with Git attribute ident. These need to be defined manually for each file in the .gitattributes file and are afterwards replaced with 40-character hexadecimal blob object name which is based only on the particular file contents. This patch simplifies handling of $Id$ keywords by removing them since they are not used anymore.
168 lines
4.9 KiB
Plaintext
168 lines
4.9 KiB
Plaintext
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, two things are
|
|
required:
|
|
|
|
- Configuration file (config.m4)
|
|
- Source code for your module
|
|
|
|
We will describe now how to create these and how to put things
|
|
together.
|
|
|
|
PREPARING YOUR SYSTEM
|
|
|
|
While the result will run on any system, a developer's setup needs these
|
|
tools:
|
|
|
|
GNU autoconf
|
|
GNU automake
|
|
GNU libtool
|
|
GNU m4
|
|
|
|
All of these are available from
|
|
|
|
ftp://ftp.gnu.org/pub/gnu/
|
|
|
|
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).
|
|
|
|
|
|
LTLIBRARY_SOURCES specifies the names of the sources files. You can
|
|
name an arbitrary number of source files here.
|
|
|
|
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_NEW_EXTENSION(foobar, foo.c bar.c, $ext_shared)
|
|
fi
|
|
------------------------------------------------------------------------------
|
|
|
|
PHP_ARG_ENABLE will automatically set the correct variables, so
|
|
that the extension will be enabled by PHP_NEW_EXTENSION in shared mode.
|
|
|
|
The first argument of PHP_NEW_EXTENSION describes the name of the
|
|
extension. The second names the source-code files. The third passes
|
|
$ext_shared which is set by PHP_ARG_ENABLE/WITH to PHP_NEW_EXTENSION.
|
|
|
|
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 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_NEW_EXTENSION(foo,.., $ext_shared) to enable
|
|
building the extension.
|
|
|
|
3. Add the following lines to your C source file:
|
|
|
|
#ifdef COMPILE_DL_FOO
|
|
ZEND_GET_MODULE(foo)
|
|
#endif
|
|
|
|
PECL SITE CONFORMITY
|
|
|
|
If you plan to release an extension to the PECL website, there are several
|
|
points to be regarded.
|
|
|
|
1. Add LICENSE or COPYING to the package.xml
|
|
|
|
2. The following should be defined in one of the extension header files
|
|
|
|
#define PHP_FOO_VERSION "1.2.3"
|
|
|
|
This macros has to be used within your foo_module_entry to indicate the
|
|
extension version.
|
|
|