From f355c4c5bbd0d02b838a056c8e081ee6fcd1e0d0 Mon Sep 17 00:00:00 2001 From: Hartmut Holzgraefe Date: Sun, 29 Jun 2003 16:07:18 +0000 Subject: ok, re-adding this mostly un-maintained awk/sed/sh nightmare for now ... --- README.EXT_SKEL | 196 +++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 194 insertions(+), 2 deletions(-) (limited to 'README.EXT_SKEL') diff --git a/README.EXT_SKEL b/README.EXT_SKEL index 261f72caf7..599e6997c4 100644 --- a/README.EXT_SKEL +++ b/README.EXT_SKEL @@ -1,2 +1,194 @@ -NOTE: ext_skel does no longer exist, it has been replaced - by the PEAR package PECL_Gen +(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. + +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 + + and everything you need is placed in directory module_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. ] + + 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 + + ./buildconf; ./configure --enable-module_name; make + + 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. + +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. + + my_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 tag in the XML documentation. + + An example: + + my_function(int arg1, int arg2 [, int arg3 [, int arg4]]) this is my 1st + + 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. + + --assign-params + --string-lens + + By default, function proto 'void foo(string bar)' creates the following: + ... + zval **bar; + ... (zend_get_parameters_ex() called in the middle...) + convert_to_string_ex(bar); + + Specifying both of these options changes the generated code to: + ... + zval **bar_arg; + int bar_len; + char *bar = NULL; + ... (zend_get_parameters_ex() called in the middle...) + convert_to_string_ex(bar_arg); + bar = Z_STRVAL_PP(bar_arg); + bar_len = Z_STRLEN_PP(bar_arg); + + You shouldn't have to ask what happens if you leave --string-lens out. If you + have to, it's questionable whether you should be reading this document. + + --with-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 my_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 my_drawtext(resource image, string text, resource font, int x, int y[, int color]) + */ +PHP_FUNCTION(my_drawtext) +{ + zval **image, **text, **font, **x, **y, **color; + int argc; + int image_id = -1; + int font_id = -1; + + argc = ZEND_NUM_ARGS(); + if (argc < 5 || argc > 6 || zend_get_parameters_ex(argc, &image, &text, &font, &x, &y, &color) == FAILURE) { + WRONG_PARAM_COUNT; + } + + ZEND_FETCH_RESOURCE(???, ???, image, image_id, "???", ???_rsrc_id); + ZEND_FETCH_RESOURCE(???, ???, font, font_id, "???", ???_rsrc_id); + + switch (argc) { + case 6: + convert_to_long_ex(color); + /* Fall-through. */ + case 5: + convert_to_long_ex(y); + convert_to_long_ex(x); + /* font: fetching resources already handled. */ + convert_to_string_ex(text); + /* image: fetching resources already handled. */ + break; + default: + WRONG_PARAM_COUNT; + } + + php_error(E_WARNING, "my_drawtext: not yet implemented"); +} +/* }}} */ + -- cgit v1.2.1