Annotation of embedaddon/php/README.SELF-CONTAINED-EXTENSIONS, revision 1.1
1.1 ! misho 1: $Id: README.SELF-CONTAINED-EXTENSIONS 242949 2007-09-26 15:44:16Z cvs2svn $
! 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
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