From c4dd7a1a684490673e25aaf4fabec5df138854c4 Mon Sep 17 00:00:00 2001 From: Lorry Tar Creator Date: Thu, 14 Mar 2013 05:42:27 +0000 Subject: Imported from /home/lorry/working-area/delta_php2/php-5.4.13.tar.bz2. --- README.SELF-CONTAINED-EXTENSIONS | 155 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 155 insertions(+) create mode 100644 README.SELF-CONTAINED-EXTENSIONS (limited to 'README.SELF-CONTAINED-EXTENSIONS') diff --git a/README.SELF-CONTAINED-EXTENSIONS b/README.SELF-CONTAINED-EXTENSIONS new file mode 100644 index 0000000..e6a3753 --- /dev/null +++ b/README.SELF-CONTAINED-EXTENSIONS @@ -0,0 +1,155 @@ +$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, 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 -- cgit v1.2.1