Annotation of embedaddon/php/README.EXT_SKEL, revision 1.1.1.2

1.1       misho       1: (NOTE: you may also want to take a look at the pear package
                      2:             PECL_Gen, a PHP-only alternative for this script that
                      3:                         supports way more extension writing tasks and is 
                      4:                         supposed to replace ext_skel completely in the long run ...)
                      5: 
                      6: WHAT IT IS
                      7: 
                      8:   It's a tool for automatically creating the basic framework for a PHP module
                      9:   and writing C code handling arguments passed to your functions from a simple
                     10:   configuration file. See an example at the end of this file.
                     11: 
                     12: HOW TO USE IT
                     13: 
                     14:   Very simple. First, change to the ext/ directory of the PHP 4 sources. If
                     15:   you just need the basic framework and will be writing all the code in your
                     16:   functions yourself, you can now do
                     17: 
                     18:    ./ext_skel --extname=module_name
                     19: 
                     20:   and everything you need is placed in directory module_name. 
                     21: 
                     22:   [ Note that GNU awk is likely required for this script to work.  Debian 
                     23:     systems seem to default to using mawk, so you may need to change the 
                     24:     #! line in skeleton/create_stubs and the cat $proto | awk line in
                     25:     ext_skel to use gawk explicitly. ]
                     26: 
                     27:   If you don't need to test the existence of any external header files, 
                     28:   libraries or functions in them, the module is already almost ready to be 
                     29:   compiled in PHP.  Just remove 3 comments in your_module_name/config.m4, 
                     30:   change back up to PHP sources top directory, and do
                     31: 
                     32:     ./buildconf; ./configure --enable-module_name; make
                     33: 
1.1.1.2 ! misho      34:   The definition of PHP_MODULE_NAME_VERSION will be present in the
        !            35:   php_module_name.h and injected into the zend_module_entry definition. This
        !            36:   is required by the PECL website for the version string conformity checks
        !            37:   against package.xml
        !            38: 
1.1       misho      39:   But if you already have planned the overall scheme of your module, what
                     40:   functions it will contain, their return types and the arguments they take
                     41:   (a very good idea) and don't want to bother yourself with creating function
                     42:   definitions and handling arguments passed yourself, it's time to create a
                     43:   function definitions file, which you will give as an argument to ext_skel
                     44:   with option
                     45: 
                     46:     --proto=filename.
                     47: 
1.1.1.2 ! misho      48: SOURCE AND HEADER FILE NAME
        !            49: 
        !            50:   ./ext_skel generates 'module_name.c' and 'php_module_name.h' as main source
        !            51:   and header files. Keep these names.
        !            52: 
        !            53:   Module functions (User functions) must be named
        !            54: 
        !            55:   module_name_function()
        !            56: 
        !            57:   When you need to expose module functions to other modules, expose functions
        !            58:   strictly needed by others. Exposed internal function must be named
        !            59: 
        !            60:   php_module_name_function()
        !            61: 
        !            62:   See also CODING_STANDARDS.
        !            63: 
        !            64: 
1.1       misho      65: FORMAT OF FUNCTION DEFINITIONS FILE
                     66: 
                     67:   All the definitions must be on one line. In it's simplest form, it's just
                     68:   the function name, e.g.
                     69: 
1.1.1.2 ! misho      70:     module_name_function
1.1       misho      71: 
                     72:   but then you'll be left with an almost empty function body without any
                     73:   argument handling.
                     74: 
                     75:   Arguments are given in parenthesis after the function name, and are of
                     76:   the form 'argument_type argument_name'. Arguments are separated from each
                     77:   other with a comma and optional space. Argument_type can be one of int,
                     78:   bool, double, float, string, array, object or mixed.
                     79: 
                     80:   An optional argument is separated from the previous by an optional space,
                     81:   then '[' and of course comma and optional space, like all the other
                     82:   arguments. You should close a row of optional arguments with same amount of
                     83:   ']'s as there where '['s. Currently, it does not harm if you forget to do it
                     84:   or there is a wrong amount of ']'s, but this may change in the future.
                     85: 
                     86:        An additional short description may be added after the parameters. 
                     87:   If present it will be filled into the 'proto' header comments in the stubs
                     88:   code and the <refpurpose> tag in the XML documentation.
                     89: 
                     90:   An example:
                     91: 
1.1.1.2 ! misho      92:     module_name_function(int arg1, int arg2 [, int arg3 [, int arg4]])
1.1       misho      93: 
1.1.1.2 ! misho      94:   Arguments arg1 and arg2 are required.
1.1       misho      95:   Arguments arg3 and arg4 are optional.
                     96: 
                     97:   If possible, the function definition should also contain it's return type
                     98:   in front of the definition. It's not actually used for any C code generating
                     99:   purposes but PHP in-source documentation instead, and as such, very useful.
                    100:   It can be any of int, double, string, bool, array, object, resource, mixed
                    101:   or void.
                    102: 
                    103:   The file must contain nothing else but function definitions, no comments or
                    104:   empty lines.
                    105: 
                    106: OTHER OPTIONS
                    107: 
                    108:     --no-help
                    109: 
                    110:   By default, ext_skel creates both comments in the source code and a test
                    111:   function to help first time module writers to get started and testing
                    112:   configuring and compiling their module. This option turns off all such things
                    113:   which may just annoy experienced PHP module coders. Especially useful with
                    114: 
                    115:     --stubs=file
                    116: 
                    117:   which will leave out also all module specific stuff and write just function
                    118:   stubs with function value declarations and passed argument handling, and
                    119:   function entries and definitions at the end of the file, for copying and
                    120:   pasting into an already existing module.
                    121: 
                    122:     --xml[=file]
                    123: 
                    124:   Creates the basics for phpdoc .xml file.
                    125: 
                    126:     --full-xml
                    127: 
                    128:   Not implemented yet. When or if there will ever be created a framework for
                    129:   self-contained extensions to use phpdoc system for their documentation, this
                    130:   option enables it on the created xml file.
                    131: 
                    132: CURRENT LIMITATIONS, BUGS AND OTHER ODDITIES
                    133: 
                    134:   Only arguments of types int, bool, double, float, string and array are
                    135:   handled. For other types you must write the code yourself. And for type
                    136:   mixed, it wouldn't even be possible to write anything, because only you
                    137:   know what to expect.
                    138:   
                    139:   It can't handle correctly, and probably never will, variable list of
                    140:   of arguments. (void foo(int bar [, ...])
                    141: 
                    142:   Don't trust the generated code too much. It tries to be useful in most of
                    143:   the situations you might encounter, but automatic code generation will never
                    144:   beat a programmer who knows the real situation at hand. ext_skel is generally
                    145:   best suited for quickly generating a wrapper for c-library functions you
                    146:   might want to have available in PHP too.
                    147: 
                    148:   This program doesn't have a --help option. It has --no-help instead.
                    149: 
                    150: EXAMPLE
                    151: 
                    152:   The following _one_ line
                    153: 
1.1.1.2 ! misho     154:   bool module_name_drawtext(resource image, string text, resource font, int x, int y [, int color])
1.1       misho     155: 
                    156:   will create this function definition for you (note that there are a few
                    157:   question marks to be replaced by you, and you must of course add your own
                    158:   value definitions too):
                    159: 
1.1.1.2 ! misho     160: /* {{{ proto bool module_name_drawtext(resource image, string text, resource font, int x, int y [, int color])
1.1       misho     161:     */
1.1.1.2 ! misho     162: PHP_FUNCTION(module_name_drawtext)
1.1       misho     163: {
                    164:     char *text = NULL;
                    165:     int argc = ZEND_NUM_ARGS();
                    166:     int image_id = -1;
                    167:     int text_len;
                    168:     int font_id = -1;
                    169:     long x;
                    170:     long y;
                    171:     long color;
                    172:     zval *image = NULL;
                    173:     zval *font = NULL;
                    174: 
                    175:     if (zend_parse_parameters(argc TSRMLS_CC, "rsrll|l", &image, &text, &text_len, &font, &x, &y, &color) == FAILURE)
                    176:         return;
                    177: 
                    178:     if (image) {
                    179:         ZEND_FETCH_RESOURCE(???, ???, image, image_id, "???", ???_rsrc_id);
                    180:     }
                    181:     if (font) {
                    182:         ZEND_FETCH_RESOURCE(???, ???, font, font_id, "???", ???_rsrc_id);
                    183:     }
                    184: 
1.1.1.2 ! misho     185:     php_error(E_WARNING, "module_name_drawtext: not yet implemented");
1.1       misho     186: }
                    187: /* }}} */
                    188: 

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>