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>
![[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