File:  [ELWIX - Embedded LightWeight unIX -] / embedaddon / php / README.EXT_SKEL
Revision 1.1.1.2 (vendor branch): download - view: text, annotated - select for diffs - revision graph
Sun Jun 15 20:03:41 2014 UTC (10 years, 6 months ago) by misho
Branches: php, MAIN
CVS tags: v5_4_29, HEAD
php 5.4.29

    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: 
   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: 
   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: 
   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: 
   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: 
   70:     module_name_function
   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: 
   92:     module_name_function(int arg1, int arg2 [, int arg3 [, int arg4]])
   93: 
   94:   Arguments arg1 and arg2 are required.
   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: 
  154:   bool module_name_drawtext(resource image, string text, resource font, int x, int y [, int color])
  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: 
  160: /* {{{ proto bool module_name_drawtext(resource image, string text, resource font, int x, int y [, int color])
  161:     */
  162: PHP_FUNCTION(module_name_drawtext)
  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: 
  185:     php_error(E_WARNING, "module_name_drawtext: not yet implemented");
  186: }
  187: /* }}} */
  188: 

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