Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 164 lines (119 sloc) 6.249 kb
f355c4c5 » Hartmut Holzgraefe
2003-06-29 ok, re-adding this mostly un-maintained awk/sed/sh nightmare for now ...
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
6b87e16b » smalyshev
2008-06-19 update the docs
99 --xml[=file]
f355c4c5 » Hartmut Holzgraefe
2003-06-29 ok, re-adding this mostly un-maintained awk/sed/sh nightmare for now ...
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
6b87e16b » smalyshev
2008-06-19 update the docs
137 /* {{{ proto bool my_drawtext(resource image, string text, resource font, int x, int y [, int color])
f355c4c5 » Hartmut Holzgraefe
2003-06-29 ok, re-adding this mostly un-maintained awk/sed/sh nightmare for now ...
138 */
139 PHP_FUNCTION(my_drawtext)
140 {
6b87e16b » smalyshev
2008-06-19 update the docs
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");
f355c4c5 » Hartmut Holzgraefe
2003-06-29 ok, re-adding this mostly un-maintained awk/sed/sh nightmare for now ...
163 }
164 /* }}} */
165
Something went wrong with that request. Please try again.