diff options
Diffstat (limited to 'docs/self-contained-extensions.md')
| -rw-r--r-- | docs/self-contained-extensions.md | 212 |
1 files changed, 108 insertions, 104 deletions
diff --git a/docs/self-contained-extensions.md b/docs/self-contained-extensions.md index 84d6aaa685..47f4c636ba 100644 --- a/docs/self-contained-extensions.md +++ b/docs/self-contained-extensions.md @@ -1,84 +1,83 @@ -# HOW TO CREATE A SELF-CONTAINED PHP EXTENSION +# 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: +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 +* Configuration file (config.m4) +* Source code for your module - We will describe now how to create these and how to put things - together. +We will describe now how to create these and how to put things together. -## PREPARING YOUR SYSTEM +## Prepairing your system - While the result will run on any system, a developer's setup needs these - tools: +While the result will run on any system, a developer's setup needs these tools: - GNU autoconf - GNU libtool - GNU m4 +* GNU autoconf +* GNU libtool +* GNU m4 - All of these are available from +All of these are available from ftp://ftp.gnu.org/pub/gnu/ -## CONVERTING AN EXISTING EXTENSION +## 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. +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/* . +```bash +mkdir /tmp/newext +cd /tmp/newext +``` - It is time to finish the module. Run: +You now have an empty directory. We will copy the files from the mysqli +extension: - $ phpize +```bash +cp -rp php-src/ext/mysqli/* . +``` - You can now ship the contents of the directory - the extension - can live completely on its own. +It is time to finish the module. Run: - The user instructions boil down to +```bash +phpize +``` - $ ./configure \ - [--with-php-config=/path/to/php-config] \ - [--with-mysql=MYSQL-DIR] - $ make install +You can now ship the contents of the directory - the extension can live +completely on its own. - The MySQL module will either use the embedded MySQL client - library or the MySQL installation in MYSQL-DIR. +The user instructions boil down to +```bash +./configure \ + [--with-php-config=/path/to/php-config] \ + [--with-mysqli=MYSQL-DIR] +make install +``` -## DEFINING THE NEW EXTENSION +The MySQL module will either use the embedded MySQL client library or the MySQL +installation in MYSQL-DIR. - Our demo extension is called "foobar". +## Defining the new extension - It consists of two source files "foo.c" and "bar.c" - (and any arbitrary amount of header files, but that is not - important here). +Our demo extension is called "foobar". - The demo extension does not reference any external - libraries (that is important, because the user does not - need to specify anything). +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. +`LTLIBRARY_SOURCES` specifies the names of the sources files. You can name an +arbitrary number of source files here. -## CREATING THE M4 CONFIGURATION FILE +## 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. +The m4 configuration can perform additional checks. For a self-contained +extension, you do not need more than a few macro calls. -``` +```m4 PHP_ARG_ENABLE([foobar], [whether to enable foobar], [AS_HELP_STRING([--enable-foobar], @@ -89,81 +88,86 @@ if test "$PHP_FOOBAR" != "no"; then 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. +`PHP_ARG_ENABLE` will automatically set the correct variables, so that the +extension will be enabled by `PHP_NEW_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. +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`. -## CREATING SOURCE FILES +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. - 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 `./ext/ext_skel.php --help` - for further information. +## Create source files - 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. +`ext_skel.php` 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 `./ext/ext_skel.php --help` +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 +## 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). +Put `config.m4` and the source files into one directory. Then, run `phpize` +(this is installed during `make install` by PHP). - For example, if you configured PHP with --prefix=/php, you would run +For example, if you configured PHP with `--prefix=/php`, you would run - $ /php/bin/phpize +```bash +/php/bin/phpize +``` - This will automatically copy the necessary build files and create - configure from your config.m4. +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. +And that's it. You now have a self-contained extension. -## INSTALLING A SELF-CONTAINED EXTENSION +## Installing a self-contained extension - An extension can be installed by running: +An extension can be installed by running: - $ ./configure \ - [--with-php-config=/path/to/php-config] - $ make install +```bash +./configure \ + [--with-php-config=/path/to/php-config] +make install +``` -## ADDING SHARED MODULE SUPPORT TO A MODULE +## 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. +In order to be useful, a self-contained extension must be loadable as a shared +module. The following 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[,..]. +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. +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: +3. Add the following lines to your C source file: -``` - #ifdef COMPILE_DL_FOO - ZEND_GET_MODULE(foo) - #endif +```c +#ifdef COMPILE_DL_FOO + ZEND_GET_MODULE(foo) +#endif ``` -## PECL SITE CONFORMITY +## PECL site conformity - If you plan to release an extension to the PECL website, there are several - points to be regarded. +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 +1. Add `LICENSE` or `COPYING` to the `package.xml` - 2. The following should be defined in one of the extension header files +2. The following should be defined in one of the extension header files - #define PHP_FOO_VERSION "1.2.3" +```c +#define PHP_FOO_VERSION "1.2.3" +``` - This macros has to be used within your foo_module_entry to indicate the - extension version. +This macros has to be used within your foo_module_entry to indicate the +extension version. |