Permalink
Browse files

ok, re-adding this mostly un-maintained awk/sed/sh nightmare for now ...

  • Loading branch information...
Hartmut Holzgraefe
Hartmut Holzgraefe committed Jun 29, 2003
1 parent 913cec6 commit f355c4c5bbd0d02b838a056c8e081ee6fcd1e0d0
View
@@ -1,2 +1,194 @@
-NOTE: ext_skel does no longer exist, it has been replaced
- by the PEAR package PECL_Gen
+(NOTE: you may also want to take a look at the pear package
+ PECL_Gen, a PHP-only alternative for this script that
+ supports way more extension writing tasks and is
+ supposed to replace ext_skel completely in the long run ...)
+
+WHAT IT IS
+
+ It's a tool for automatically creating the basic framework for a PHP module
+ and writing C code handling arguments passed to your functions from a simple
+ configuration file. See an example at the end of this file.
+
+HOW TO USE IT
+
+ Very simple. First, change to the ext/ directory of the PHP 4 sources. If
+ you just need the basic framework and will be writing all the code in your
+ functions yourself, you can now do
+
+ ./ext_skel --extname=module_name
+
+ and everything you need is placed in directory module_name.
+
+ [ Note that GNU awk is likely required for this script to work. Debian
+ systems seem to default to using mawk, so you may need to change the
+ #! line in skeleton/create_stubs and the cat $proto | awk line in
+ ext_skel to use gawk explicitly. ]
+
+ If you don't need to test the existence of any external header files,
+ libraries or functions in them, the module is already almost ready to be
+ compiled in PHP. Just remove 3 comments in your_module_name/config.m4,
+ change back up to PHP sources top directory, and do
+
+ ./buildconf; ./configure --enable-module_name; make
+
+ But if you already have planned the overall scheme of your module, what
+ functions it will contain, their return types and the arguments they take
+ (a very good idea) and don't want to bother yourself with creating function
+ definitions and handling arguments passed yourself, it's time to create a
+ function definitions file, which you will give as an argument to ext_skel
+ with option
+
+ --proto=filename.
+
+FORMAT OF FUNCTION DEFINITIONS FILE
+
+ All the definitions must be on one line. In it's simplest form, it's just
+ the function name, e.g.
+
+ my_function
+
+ but then you'll be left with an almost empty function body without any
+ argument handling.
+
+ Arguments are given in parenthesis after the function name, and are of
+ the form 'argument_type argument_name'. Arguments are separated from each
+ other with a comma and optional space. Argument_type can be one of int,
+ bool, double, float, string, array, object or mixed.
+
+ An optional argument is separated from the previous by an optional space,
+ then '[' and of course comma and optional space, like all the other
+ arguments. You should close a row of optional arguments with same amount of
+ ']'s as there where '['s. Currently, it does not harm if you forget to do it
+ or there is a wrong amount of ']'s, but this may change in the future.
+
+ An additional short description may be added after the parameters.
+ If present it will be filled into the 'proto' header comments in the stubs
+ code and the <refpurpose> tag in the XML documentation.
+
+ An example:
+
+ my_function(int arg1, int arg2 [, int arg3 [, int arg4]]) this is my 1st
+
+ Arguments arg3 and arg4 are optional.
+
+ If possible, the function definition should also contain it's return type
+ in front of the definition. It's not actually used for any C code generating
+ purposes but PHP in-source documentation instead, and as such, very useful.
+ It can be any of int, double, string, bool, array, object, resource, mixed
+ or void.
+
+ The file must contain nothing else but function definitions, no comments or
+ empty lines.
+
+OTHER OPTIONS
+
+ --no-help
+
+ By default, ext_skel creates both comments in the source code and a test
+ function to help first time module writers to get started and testing
+ configuring and compiling their module. This option turns off all such things
+ which may just annoy experienced PHP module coders. Especially useful with
+
+ --stubs=file
+
+ which will leave out also all module specific stuff and write just function
+ stubs with function value declarations and passed argument handling, and
+ function entries and definitions at the end of the file, for copying and
+ pasting into an already existing module.
+
+ --assign-params
+ --string-lens
+
+ By default, function proto 'void foo(string bar)' creates the following:
+ ...
+ zval **bar;
+ ... (zend_get_parameters_ex() called in the middle...)
+ convert_to_string_ex(bar);
+
+ Specifying both of these options changes the generated code to:
+ ...
+ zval **bar_arg;
+ int bar_len;
+ char *bar = NULL;
+ ... (zend_get_parameters_ex() called in the middle...)
+ convert_to_string_ex(bar_arg);
+ bar = Z_STRVAL_PP(bar_arg);
+ bar_len = Z_STRLEN_PP(bar_arg);
+
+ You shouldn't have to ask what happens if you leave --string-lens out. If you
+ have to, it's questionable whether you should be reading this document.
+
+ --with-xml[=file]
+
+ Creates the basics for phpdoc .xml file.
+
+ --full-xml
+
+ Not implemented yet. When or if there will ever be created a framework for
+ self-contained extensions to use phpdoc system for their documentation, this
+ option enables it on the created xml file.
+
+CURRENT LIMITATIONS, BUGS AND OTHER ODDITIES
+
+ Only arguments of types int, bool, double, float, string and array are
+ handled. For other types you must write the code yourself. And for type
+ mixed, it wouldn't even be possible to write anything, because only you
+ know what to expect.
+
+ It can't handle correctly, and probably never will, variable list of
+ of arguments. (void foo(int bar [, ...])
+
+ Don't trust the generated code too much. It tries to be useful in most of
+ the situations you might encounter, but automatic code generation will never
+ beat a programmer who knows the real situation at hand. ext_skel is generally
+ best suited for quickly generating a wrapper for c-library functions you
+ might want to have available in PHP too.
+
+ This program doesn't have a --help option. It has --no-help instead.
+
+EXAMPLE
+
+ The following _one_ line
+
+ bool my_drawtext(resource image, string text, resource font, int x, int y [, int color])
+
+ will create this function definition for you (note that there are a few
+ question marks to be replaced by you, and you must of course add your own
+ value definitions too):
+
+/* {{{ proto bool my_drawtext(resource image, string text, resource font, int x, int y[, int color])
+ */
+PHP_FUNCTION(my_drawtext)
+{
+ zval **image, **text, **font, **x, **y, **color;
+ int argc;
+ int image_id = -1;
+ int font_id = -1;
+
+ argc = ZEND_NUM_ARGS();
+ if (argc < 5 || argc > 6 || zend_get_parameters_ex(argc, &image, &text, &font, &x, &y, &color) == FAILURE) {
+ WRONG_PARAM_COUNT;
+ }
+
+ ZEND_FETCH_RESOURCE(???, ???, image, image_id, "???", ???_rsrc_id);
+ ZEND_FETCH_RESOURCE(???, ???, font, font_id, "???", ???_rsrc_id);
+
+ switch (argc) {
+ case 6:
+ convert_to_long_ex(color);
+ /* Fall-through. */
+ case 5:
+ convert_to_long_ex(y);
+ convert_to_long_ex(x);
+ /* font: fetching resources already handled. */
+ convert_to_string_ex(text);
+ /* image: fetching resources already handled. */
+ break;
+ default:
+ WRONG_PARAM_COUNT;
+ }
+
+ php_error(E_WARNING, "my_drawtext: not yet implemented");
+}
+/* }}} */
+
Oops, something went wrong.

0 comments on commit f355c4c

Please sign in to comment.