diff options
Diffstat (limited to 'README.EXT_SKEL')
-rw-r--r-- | README.EXT_SKEL | 178 |
1 files changed, 17 insertions, 161 deletions
diff --git a/README.EXT_SKEL b/README.EXT_SKEL index 5ac48ec4fa..2d093694d1 100644 --- a/README.EXT_SKEL +++ b/README.EXT_SKEL @@ -1,188 +1,44 @@ -(NOTE: you may also want to take a look at the pear package - PECL_Gen, a PHP-only alternative for this script that - supports way more extension writing tasks and is - supposed to replace ext_skel completely in the long run ...) - WHAT IT IS - It's a tool for automatically creating the basic framework for a PHP module - and writing C code handling arguments passed to your functions from a simple - configuration file. See an example at the end of this file. + It's a tool for automatically creating the basic framework for a PHP extension. HOW TO USE IT - Very simple. First, change to the ext/ directory of the PHP 4 sources. If - you just need the basic framework and will be writing all the code in your - functions yourself, you can now do - - ./ext_skel --extname=module_name + Very simple. First, change to the ext/ directory of the PHP sources. Then + run the following - and everything you need is placed in directory module_name. + php ext_skel.php --ext extension_name - [ Note that GNU awk is likely required for this script to work. Debian - systems seem to default to using mawk, so you may need to change the - #! line in skeleton/create_stubs and the cat $proto | awk line in - ext_skel to use gawk explicitly. ] + and everything you need will be placed in directory ext/extension_name. If you don't need to test the existence of any external header files, - libraries or functions in them, the module is already almost ready to be - compiled in PHP. Just remove 3 comments in your_module_name/config.m4, - change back up to PHP sources top directory, and do + libraries or functions in them, the extension is ready to be compiled in + PHP. To compile the extension, run the following: - ./buildconf; ./configure --enable-module_name; make + ./buildconf; ./configure --enable-extension_name; make - The definition of PHP_MODULE_NAME_VERSION will be present in the - php_module_name.h and injected into the zend_module_entry definition. This + The definition of PHP_extension_NAME_VERSION will be present in the + php_extension_name.h and injected into the zend_extension_entry definition. This is required by the PECL website for the version string conformity checks against package.xml - But if you already have planned the overall scheme of your module, what - functions it will contain, their return types and the arguments they take - (a very good idea) and don't want to bother yourself with creating function - definitions and handling arguments passed yourself, it's time to create a - function definitions file, which you will give as an argument to ext_skel - with option - - --proto=filename. - SOURCE AND HEADER FILE NAME - ./ext_skel generates 'module_name.c' and 'php_module_name.h' as main source - and header files. Keep these names. + The ext_skel.php script generates 'extension_name.c' and 'php_extension_name.h' + as the main source and header files. Keep these names. - Module functions (User functions) must be named + extension functions (User functions) must be named - module_name_function() + extension_name_function() - When you need to expose module functions to other modules, expose functions + When you need to expose extension functions to other extensions, expose functions strictly needed by others. Exposed internal function must be named - php_module_name_function() + php_extension_name_function() See also CODING_STANDARDS. - -FORMAT OF FUNCTION DEFINITIONS FILE - - All the definitions must be on one line. In it's simplest form, it's just - the function name, e.g. - - module_name_function - - but then you'll be left with an almost empty function body without any - argument handling. - - Arguments are given in parenthesis after the function name, and are of - the form 'argument_type argument_name'. Arguments are separated from each - other with a comma and optional space. Argument_type can be one of int, - bool, double, float, string, array, object or mixed. - - An optional argument is separated from the previous by an optional space, - then '[' and of course comma and optional space, like all the other - arguments. You should close a row of optional arguments with same amount of - ']'s as there where '['s. Currently, it does not harm if you forget to do it - or there is a wrong amount of ']'s, but this may change in the future. - - An additional short description may be added after the parameters. - If present it will be filled into the 'proto' header comments in the stubs - code and the <refpurpose> tag in the XML documentation. - - An example: - - module_name_function(int arg1, int arg2 [, int arg3 [, int arg4]]) - - Arguments arg1 and arg2 are required. - Arguments arg3 and arg4 are optional. - - If possible, the function definition should also contain it's return type - in front of the definition. It's not actually used for any C code generating - purposes but PHP in-source documentation instead, and as such, very useful. - It can be any of int, double, string, bool, array, object, resource, mixed - or void. - - The file must contain nothing else but function definitions, no comments or - empty lines. - OTHER OPTIONS - --no-help - - By default, ext_skel creates both comments in the source code and a test - function to help first time module writers to get started and testing - configuring and compiling their module. This option turns off all such things - which may just annoy experienced PHP module coders. Especially useful with - - --stubs=file - - which will leave out also all module specific stuff and write just function - stubs with function value declarations and passed argument handling, and - function entries and definitions at the end of the file, for copying and - pasting into an already existing module. - - --xml[=file] - - Creates the basics for phpdoc .xml file. - - --full-xml - - Not implemented yet. When or if there will ever be created a framework for - self-contained extensions to use phpdoc system for their documentation, this - option enables it on the created xml file. - -CURRENT LIMITATIONS, BUGS AND OTHER ODDITIES - - Only arguments of types int, bool, double, float, string and array are - handled. For other types you must write the code yourself. And for type - mixed, it wouldn't even be possible to write anything, because only you - know what to expect. - - It can't handle correctly, and probably never will, variable list of - of arguments. (void foo(int bar [, ...]) - - Don't trust the generated code too much. It tries to be useful in most of - the situations you might encounter, but automatic code generation will never - beat a programmer who knows the real situation at hand. ext_skel is generally - best suited for quickly generating a wrapper for c-library functions you - might want to have available in PHP too. - - This program doesn't have a --help option. It has --no-help instead. - -EXAMPLE - - The following _one_ line - - bool module_name_drawtext(resource image, string text, resource font, int x, int y [, int color]) - - will create this function definition for you (note that there are a few - question marks to be replaced by you, and you must of course add your own - value definitions too): - -/* {{{ proto bool module_name_drawtext(resource image, string text, resource font, int x, int y [, int color]) - */ -PHP_FUNCTION(module_name_drawtext) -{ - char *text = NULL; - int argc = ZEND_NUM_ARGS(); - int image_id = -1; - size_t text_len; - int font_id = -1; - zend_long x; - zend_long y; - zend_long color; - zval *image = NULL; - zval *font = NULL; - - if (zend_parse_parameters(argc, "rsrll|l", &image, &text, &text_len, &font, &x, &y, &color) == FAILURE) - return; - - if (image) { - ZEND_FETCH_RESOURCE(???, ???, image, image_id, "???", ???_rsrc_id); - } - if (font) { - ZEND_FETCH_RESOURCE(???, ???, font, font_id, "???", ???_rsrc_id); - } - - php_error(E_WARNING, "module_name_drawtext: not yet implemented"); -} -/* }}} */ + Run php ext_skel.php --help to see the available options. |