Annotation of embedaddon/php/README.EXT_SKEL, revision 1.1
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:
! 34: But if you already have planned the overall scheme of your module, what
! 35: functions it will contain, their return types and the arguments they take
! 36: (a very good idea) and don't want to bother yourself with creating function
! 37: definitions and handling arguments passed yourself, it's time to create a
! 38: function definitions file, which you will give as an argument to ext_skel
! 39: with option
! 40:
! 41: --proto=filename.
! 42:
! 43: FORMAT OF FUNCTION DEFINITIONS FILE
! 44:
! 45: All the definitions must be on one line. In it's simplest form, it's just
! 46: the function name, e.g.
! 47:
! 48: my_function
! 49:
! 50: but then you'll be left with an almost empty function body without any
! 51: argument handling.
! 52:
! 53: Arguments are given in parenthesis after the function name, and are of
! 54: the form 'argument_type argument_name'. Arguments are separated from each
! 55: other with a comma and optional space. Argument_type can be one of int,
! 56: bool, double, float, string, array, object or mixed.
! 57:
! 58: An optional argument is separated from the previous by an optional space,
! 59: then '[' and of course comma and optional space, like all the other
! 60: arguments. You should close a row of optional arguments with same amount of
! 61: ']'s as there where '['s. Currently, it does not harm if you forget to do it
! 62: or there is a wrong amount of ']'s, but this may change in the future.
! 63:
! 64: An additional short description may be added after the parameters.
! 65: If present it will be filled into the 'proto' header comments in the stubs
! 66: code and the <refpurpose> tag in the XML documentation.
! 67:
! 68: An example:
! 69:
! 70: my_function(int arg1, int arg2 [, int arg3 [, int arg4]]) this is my 1st
! 71:
! 72: Arguments arg3 and arg4 are optional.
! 73:
! 74: If possible, the function definition should also contain it's return type
! 75: in front of the definition. It's not actually used for any C code generating
! 76: purposes but PHP in-source documentation instead, and as such, very useful.
! 77: It can be any of int, double, string, bool, array, object, resource, mixed
! 78: or void.
! 79:
! 80: The file must contain nothing else but function definitions, no comments or
! 81: empty lines.
! 82:
! 83: OTHER OPTIONS
! 84:
! 85: --no-help
! 86:
! 87: By default, ext_skel creates both comments in the source code and a test
! 88: function to help first time module writers to get started and testing
! 89: configuring and compiling their module. This option turns off all such things
! 90: which may just annoy experienced PHP module coders. Especially useful with
! 91:
! 92: --stubs=file
! 93:
! 94: which will leave out also all module specific stuff and write just function
! 95: stubs with function value declarations and passed argument handling, and
! 96: function entries and definitions at the end of the file, for copying and
! 97: pasting into an already existing module.
! 98:
! 99: --xml[=file]
! 100:
! 101: Creates the basics for phpdoc .xml file.
! 102:
! 103: --full-xml
! 104:
! 105: Not implemented yet. When or if there will ever be created a framework for
! 106: self-contained extensions to use phpdoc system for their documentation, this
! 107: option enables it on the created xml file.
! 108:
! 109: CURRENT LIMITATIONS, BUGS AND OTHER ODDITIES
! 110:
! 111: Only arguments of types int, bool, double, float, string and array are
! 112: handled. For other types you must write the code yourself. And for type
! 113: mixed, it wouldn't even be possible to write anything, because only you
! 114: know what to expect.
! 115:
! 116: It can't handle correctly, and probably never will, variable list of
! 117: of arguments. (void foo(int bar [, ...])
! 118:
! 119: Don't trust the generated code too much. It tries to be useful in most of
! 120: the situations you might encounter, but automatic code generation will never
! 121: beat a programmer who knows the real situation at hand. ext_skel is generally
! 122: best suited for quickly generating a wrapper for c-library functions you
! 123: might want to have available in PHP too.
! 124:
! 125: This program doesn't have a --help option. It has --no-help instead.
! 126:
! 127: EXAMPLE
! 128:
! 129: The following _one_ line
! 130:
! 131: bool my_drawtext(resource image, string text, resource font, int x, int y [, int color])
! 132:
! 133: will create this function definition for you (note that there are a few
! 134: question marks to be replaced by you, and you must of course add your own
! 135: value definitions too):
! 136:
! 137: /* {{{ proto bool my_drawtext(resource image, string text, resource font, int x, int y [, int color])
! 138: */
! 139: PHP_FUNCTION(my_drawtext)
! 140: {
! 141: char *text = NULL;
! 142: int argc = ZEND_NUM_ARGS();
! 143: int image_id = -1;
! 144: int text_len;
! 145: int font_id = -1;
! 146: long x;
! 147: long y;
! 148: long color;
! 149: zval *image = NULL;
! 150: zval *font = NULL;
! 151:
! 152: if (zend_parse_parameters(argc TSRMLS_CC, "rsrll|l", &image, &text, &text_len, &font, &x, &y, &color) == FAILURE)
! 153: return;
! 154:
! 155: if (image) {
! 156: ZEND_FETCH_RESOURCE(???, ???, image, image_id, "???", ???_rsrc_id);
! 157: }
! 158: if (font) {
! 159: ZEND_FETCH_RESOURCE(???, ???, font, font_id, "???", ???_rsrc_id);
! 160: }
! 161:
! 162: php_error(E_WARNING, "my_drawtext: not yet implemented");
! 163: }
! 164: /* }}} */
! 165:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to README.EXT_SKEL CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / php