cvs: pear /PECL_Gen manual.html manual.xml
| From: | Hartmut Holzgraefe | Date: | Sat, 12 Jul 2003 07:16:18 +0000 |
| Subject: | cvs: pear /PECL_Gen manual.html manual.xml | ||
| Groups: | php.pear.cvs | ||
| Request: | Send a blank email to pear-cvs+get-11451@lists.php.net to get a copy of this message | ||
hholzgra Sat Jul 12 03:16:18 2003 EDT
Modified files:
/pear/PECL_Gen manual.xml manual.html
Log:
documentation now complete and up to date
Index: pear/PECL_Gen/manual.xml diff -u pear/PECL_Gen/manual.xml:1.1 pear/PECL_Gen/manual.xml:1.2 --- pear/PECL_Gen/manual.xml:1.1 Fri Jul 11 04:36:07 2003 +++ pear/PECL_Gen/manual.xml Sat Jul 12 03:16:18 2003 @@ -16,7 +16,7 @@ configuration file. </para> <para> - It also supports the simpler (but less powerfull) prototype file + It also supports the simpler (but less powerful) prototype file format as used by the shell script <literal>ext_skel</literal> that is part of the PHP source code. </para> @@ -33,15 +33,85 @@ <section> <title>Features</title> <para> - + <literal>pecl-gen</literal> tries to support as many extension + writing aspects as possible. This currently includes code and documentation + generation for: + <simplelist> + <member>functions</member> + <member>constants</member> + <member><literal>php.ini</literal> configuration directives</member> + <member>resource types</member> + <member>per-thread global variables</member> + </simplelist> + </para> + <para> + <literal>pecl-gen</literal> also generates + <filename>config.m4</filename> + configuration files for Unix-like build environments, + VisualStudio <filename>*.dsp</filename> project files for Windows + and the <filename>package.xml</filename> files needed for + PEAR/PECL packaging. + </para> + <para> + DocBook XML documentation templates suitable for inclusion in the + PHP or PEAR manual is generated in the hope that it will ease the + task of documenting extension. + </para> + <para> + Test scripts for automatic regression testing are already created + but due to some missing features within the "<literal>make + test</literal>" infrastructure it is not possible to use the + generated tests with standalone PECL extensions right now. </para> </section> <section> <title>How to use it</title> <para> - - </para> + There are currently three different modes of operation for + <literal>pecl-gen</literal>. In its default mode it can create a complete + ready-to-compile extension from an XML description (documented in + the next chapter). In <literal>ext_skel</literal> compatibility + mode it generates the extension from some command line parameters + and an optional function prototype file and in immediate mode it + just takes a function prototype from command line and writes a + C code skeleton for just that function to standard output. + </para> + <para> + <literal>ext_skel</literal> compatibility mode is not documented + here, please refer to the original <literal>ext_skel</literal> + documentation instead. + </para> + <para> + Below you find a hardcopy of the <literal>pecl-gen + --help</literal> output: + </para> + <screen> +pecl-gen [-h] [--extname=name] [--proto=file] [--skel=dir] [--stubs=file] + [--no-help] [--xml[=file]] [--full-xml] [--function=proto] [specfile.xml] + + -h|--help this message + --force overwrite existing directories + --function create a function skeleton from a proto right away + --version show version info + + the following options are inherited from ext_skel: + + --extname=module module is the name of your extension + --proto=file file contains prototypes of functions to create + --xml generate xml documentation to be added to phpdoc-cvs + + these wait for functionality to be implemented and are ignored for now ... + --stubs=file generate only function stubs in file + --no-help don't try to be nice and create comments in the code + and helper functions to test if the module compiled + + these are accepted for backwards compatibility reasons but not used ... + --full-xml generate xml documentation for a self-contained extension + (this was also a no-op in ext_skel) + --skel=dir path to the skeleton directory + (skeleton stuff is now self-contained) + </screen> </section> </chapter> @@ -54,16 +124,16 @@ <para> The top level container tag describing an extension is the <sgmltag>extension</sgmltag> tag. The name of the extension - is given in the <literal>name</literal> attibute. The extension + is given in the <literal>name</literal> attribute. The extension name has to be a valid C name as it is used as both the extensions - directory name and the basename for several C symbols within the + directory name and the base name for several C symbols within the generated C code. </para> <para> The tags <sgmltag>summary</sgmltag> and <sgmltag>description</sgmltag> should be added at the very top of - your extesnions. The summary should be a short one-line - description of the extension while the actualy description can be + your extensions. The summary should be a short one-line + description of the extension while the actually description can be as detailed as you like. Both are later used to generate the <literal>package.xml</literal> file and the documentation for your extension. The summary line is also put into the @@ -76,7 +146,7 @@ <extension name="sample"> <summary>A sample PHP extension</summary> <description> - This is a sample extension speification + This is a sample extension specification showing how to use PECL_Gen for extension generation. </description> @@ -91,7 +161,7 @@ <para> The release information for your extension should include the extension authors and maintainers, the version number, state and - release date, the chosen license and maybe a changelog describing + release date, the chosen license and maybe a change log describing previous releases. It is also possible to specify an image file to be used as a product logo with the <literal>phpinfo()</literal> output block for the extension. @@ -100,7 +170,7 @@ The <sgmltag>maintainers</sgmltag>, <sgmltag>release</sgmltag> and <sgmltag>changelog</sgmltag> tags specifications are taken from the PEAR <literal>package.xml</literal> specification so please - refere to the PEAR documentation here for now. + refer to the PEAR documentation here for now. </para> <example> <title>Release information</title> @@ -146,7 +216,7 @@ <para> The <sgmltag>license</sgmltag> tag is a little more restrictive as its <literal>package.xml</literal> counterpart as it is used to - decide which license text should actualy be written to the + decide which license text should actually be written to the <literal>LICENSE</literal>. For now you have to specify either <literal>PHP</literal>, <literal>BSD</literal> or <literal>LGPL</literal>, any other value is taken as @@ -189,29 +259,120 @@ <para> Dependencies are specified within the <sgmltag>deps</sgmltag> environment. Within the <sgmltag>deps</sgmltag> itself it is - possible to set the programing language and target platforms using + possible to set the programming language and target platforms using the <literal>language=...</literal> and <literal>platform=...</literal> attributes. </para> <para> + Supported languages are C (<literal>lang="c"</literal>) and C++ + (<literal>language="cpp"</literal>). The language selection + does not influence code generation itself + (<literal>pecl-gen</literal> always generates C code) but the way + extensions are compiled and linked. C++ should only be selected to + interface to external C++ libraries. </para> + <para> + Supported platforms are currently Unix-like systems + (<literal>platform="unix"</literal>), Microsoft Windows + (<literal>platform="win32"</literal>) or both (<literal>platform="all"</literal>). + </para> + <example> + <title>Dependencies</title> + <programlisting> +<![CDATA[ +... + <deps language="cpp" platform="win32"> + ... + </deps> +... +]]> + </programlisting> + </example> <section> <title><literal>--with...</literal></title> <para> - </para> + When building an extension on Unix-like systems or within the + Cygwin environment under Windows the <literal>configure</literal> + script will try to figure out where external libraries and header + files needed by an extension are installed on the target system. + Using a "with" option it is possible to specify where to actually + look for libraries and headers. This way it is possible to + override search paths if things are not installed in the default + system paths or to specify the exact version of a package to be + used if multiple versions are installed on the target system. + </para> + <para> + The <sgmltag>with</sgmltag> tag takes three attributes: + <literal>name=...</literal> for the actual name of the "with" + option, <literal>testfile</literal> for the relative path of a + file to check for while running the <literal>configure</literal> + script and a list of default paths to check if no path is given + as an argument to the "with" option in + <literal>defaults</literal>. + </para> + <para> + Name and defaults are set to the extension base name and + "/usr:/usr/local" if no values are given. The testfile attribute + is mandatory. + </para> + <para> + Textual data enclosed by the <sgmltag>with</sgmltag> is used to + describe the "with" option in the output of <literal>configure + --help</literal> calls. + </para> + <example> + <title><literal>--with...</literal></title> + <programlisting> +<![CDATA[ +... + <with defaults='/usr:/usr/local' testfile='include/sample.h'>sample install</with> +... +]]> + </programlisting> + </example> </section> <section> <title>Libraries</title> <para> - </para> + Needed external libraries are specified using the + <sgmltag>lib</sgmltag> tag. The <literal>name=...</literal> + attribute is mandatory and takes the library base name. A library + dependency by the name "sample" is actually referring to a library + file named <filename>libsample.a</filename> for a static or + <filename>libsample.so</filename> for a dynamic library on + Unix-like systems or to <filename>sample.DLL</filename> on + Windows. + </para> + <para> + It is possible to specify the name of a function symbol expected + to be provided by the library using the + <literal>function=...</literal> attribute. This function symbol + is being looked for when <literal>configure</literal> is run for + the extension. This way it is possible to verify that the right + version of a library was found. With VisualStudio on windows it + is not possible to perform this check, in this case the library + is just added to the project file. + </para> + <example> + <title>Library dependencies</title> + <programlisting> +<![CDATA[ +... + <lib name="sample_u" platform="unix" function="sample_v2" /> + <lib name="sample_w" platform="win32" /> + <lib name="sample" platform="all" /> +... +]]> + </programlisting> + </example> </section> <section> <title>Header files</title> <para> - It is possible to speify header files needed by the extension + It is possible to specify header files needed by the extension using the <sgmltag>header</sgmltag>. Any headers specified have to exist in the include path set for compiling (see also the section on <literal>--with</literal> @@ -226,6 +387,17 @@ for header file availability has not been added yet. </para> </note> + <example> + <title>Header file dependencies</title> + <programlisting> +<![CDATA[ +... + <header name="include_me_first.h" prepend="yes" /> + <header name="sample.h" /> +... +]]> + </programlisting> + </example> </section> <section> @@ -373,7 +545,7 @@ <listitem> <simpara> The request shutdown function. This is called by PHP server - modules before actualy executing a PHP script request or once + modules before actually executing a PHP script request or once right after <literal>MINIT()</literal> for standalone binaries (CGI or CLI). </simpara> @@ -386,7 +558,7 @@ The request shutdown function. This is called by PHP server modules after execution of PHP code has been finished or terminated. - Is called even if critical PHP errors occured but you can not + Is called even if critical PHP errors occurred but you can not rely on it being called on critical errors or crashes on the C level. </simpara> @@ -504,7 +676,7 @@ they can be defined using C code within the <sgmltag>code</sgmltag> tag. </para> <para> - Module globlals that are only global to a single request need to + Module globals that are only global to a single request need to be managed to ensure thread safety and initialization on request initialization. <literal>php.ini</literal> directive values are also stored as module globals but need some additional definitions. @@ -552,7 +724,7 @@ </para> <para> Directive default values are passed to the engine as strings, so - you may not use any C constats or preprocessor macros here. The + you may not use any C constants or preprocessor macros here. The default value strings are parsed by the <literal>OnUpdate</literal> handler registered for that directive. No value checking takes place during extension code @@ -572,7 +744,7 @@ <term>system</term> <listitem> <para> - may only be set globaly in <literal>php.ini</literal> or the + may only be set globally in <literal>php.ini</literal> or the web server configuration </para> </listitem> @@ -598,7 +770,7 @@ generate documentation for the defined directive. <sgmltag>global</sgmltag> definitions may also include content data but it is for internal documentation only, it is not - used in DocBooc XML generation (yet). + used in DocBook XML generation (yet). </para> <example> <title>Globals</title> @@ -646,7 +818,7 @@ payload needs to be cleaned up as well you have to add an appropriate C code snippet that takes care of this using the <sgmltag>destruct</sgmltag> tag. Within the destructor snippet you - may refere to the allocated payload using the + may refer to the allocated payload using the <literal>resource</literal> pointer variable. </para> <para> @@ -704,7 +876,7 @@ <section> <title>Custom code</title> <para> - Custum code may be added to your extension source files using the + Custom code may be added to your extension source files using the <sgmltag>code</sgmltag> tags. The <literal>role=...</literal> and <literal>position=...</literal> tags specify the actual place in there generated source files where your code should be Index: pear/PECL_Gen/manual.html diff -u pear/PECL_Gen/manual.html:1.1 pear/PECL_Gen/manual.html:1.2 --- pear/PECL_Gen/manual.html:1.1 Fri Jul 11 04:36:07 2003 +++ pear/PECL_Gen/manual.html Sat Jul 12 03:16:18 2003 @@ -57,46 +57,46 @@ ></DT ><DT ><A -HREF="#AEN20" +HREF="#AEN36" >How to use it</A ></DT ></DL ></DD ><DT >2. <A -HREF="#AEN23" +HREF="#AEN47" >The XML description</A ></DT ><DD ><DL ><DT ><A -HREF="#AEN25" +HREF="#AEN49" >Basics</A ></DT ><DT ><A -HREF="#AEN38" +HREF="#AEN62" >Release information</A ></DT ><DT ><A -HREF="#AEN70" +HREF="#AEN94" >Dependencies</A ></DT ><DT ><A -HREF="#AEN89" +HREF="#AEN166" >Functions</A ></DT ><DT ><A -HREF="#AEN195" +HREF="#AEN272" >Constants</A ></DT ><DT ><A -HREF="#AEN210" +HREF="#AEN287" ><TT CLASS="literal" >php.ini</TT @@ -104,27 +104,27 @@ ></DT ><DT ><A -HREF="#AEN278" +HREF="#AEN355" >Resources</A ></DT ><DT ><A -HREF="#AEN300" +HREF="#AEN377" >Classes</A ></DT ><DT ><A -HREF="#AEN303" +HREF="#AEN380" >Streams</A ></DT ><DT ><A -HREF="#AEN306" +HREF="#AEN383" >Custom code</A ></DT ><DT ><A -HREF="#AEN319" +HREF="#AEN396" >Tests</A ></DT ></DL @@ -155,7 +155,7 @@ configuration file. </P ><P -> It also supports the simpler (but less powerfull) prototype file +> It also supports the simpler (but less powerful) prototype file format as used by the shell script <TT CLASS="literal" >ext_skel</TT @@ -192,7 +192,79 @@ ></A >Features</H1 ><P -> +> <TT +CLASS="literal" +>pecl-gen</TT +> tries to support as many extension + writing aspects as possible. This currently includes code and documentation + generation for: + <P +></P +><TABLE +BORDER="0" +><TBODY +><TR +><TD +>functions</TD +></TR +><TR +><TD +>constants</TD +></TR +><TR +><TD +><TT +CLASS="literal" +>php.ini</TT +> configuration directives</TD +></TR +><TR +><TD +>resource types</TD +></TR +><TR +><TD +>per-thread global variables</TD +></TR +></TBODY +></TABLE +><P +></P +> + </P +><P +> <TT +CLASS="literal" +>pecl-gen</TT +> also generates + <TT +CLASS="filename" +>config.m4</TT +> + configuration files for Unix-like build environments, + VisualStudio <TT +CLASS="filename" +>*.dsp</TT +> project files for Windows + and the <TT +CLASS="filename" +>package.xml</TT +> files needed for + PEAR/PECL packaging. + </P +><P +> DocBook XML documentation templates suitable for inclusion in the + PHP or PEAR manual is generated in the hope that it will ease the + task of documenting extension. + </P +><P +> Test scripts for automatic regression testing are already created + but due to some missing features within the "<TT +CLASS="literal" +>make + test</TT +>" infrastructure it is not possible to use the + generated tests with standalone PECL extensions right now. </P ></DIV ><DIV @@ -200,19 +272,85 @@ ><HR><H1 CLASS="section" ><A -NAME="AEN20" +NAME="AEN36" ></A >How to use it</H1 ><P -> +> There are currently three different modes of operation for + <TT +CLASS="literal" +>pecl-gen</TT +>. In its default mode it can create a complete + ready-to-compile extension from an XML description (documented in + the next chapter). In <TT +CLASS="literal" +>ext_skel</TT +> compatibility + mode it generates the extension from some command line parameters + and an optional function prototype file and in immediate mode it + just takes a function prototype from command line and writes a + C code skeleton for just that function to standard output. + </P +><P +> <TT +CLASS="literal" +>ext_skel</TT +> compatibility mode is not documented + here, please refer to the original <TT +CLASS="literal" +>ext_skel</TT +> + documentation instead. </P +><P +> Below you find a hardcopy of the <TT +CLASS="literal" +>pecl-gen + --help</TT +> output: + </P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +CELLPADDING="5" +><TR +><TD +><PRE +CLASS="screen" +>pecl-gen [-h] [--extname=name] [--proto=file] [--skel=dir] [--stubs=file] + [--no-help] [--xml[=file]] [--full-xml] [--function=proto] [specfile.xml] + + -h|--help this message + --force overwrite existing directories + --function create a function skeleton from a proto right away + --version show version info + + the following options are inherited from ext_skel: + + --extname=module module is the name of your extension + --proto=file file contains prototypes of functions to create + --xml generate xml documentation to be added to phpdoc-cvs + + these wait for functionality to be implemented and are ignored for now ... + --stubs=file generate only function stubs in file + --no-help don't try to be nice and create comments in the code + and helper functions to test if the module compiled + + these are accepted for backwards compatibility reasons but not used ... + --full-xml generate xml documentation for a self-contained extension + (this was also a no-op in ext_skel) + --skel=dir path to the skeleton directory + (skeleton stuff is now self-contained)</PRE +></TD +></TR +></TABLE ></DIV ></DIV ><DIV CLASS="chapter" ><HR><H1 ><A -NAME="AEN23" +NAME="AEN47" >Chapter 2. The XML description</A ></H1 ><DIV @@ -220,7 +358,7 @@ ><H1 CLASS="section" ><A -NAME="AEN25" +NAME="AEN49" ></A >Basics</H1 ><P @@ -238,9 +376,9 @@ is given in the <TT CLASS="literal" >name</TT -> attibute. The extension +> attribute. The extension name has to be a valid C name as it is used as both the extensions - directory name and the basename for several C symbols within the + directory name and the base name for several C symbols within the generated C code. </P ><P @@ -264,8 +402,8 @@ CLASS="sgmltag" >></B > should be added at the very top of - your extesnions. The summary should be a short one-line - description of the extension while the actualy description can be + your extensions. The summary should be a short one-line + description of the extension while the actually description can be as detailed as you like. Both are later used to generate the <TT CLASS="literal" @@ -288,7 +426,7 @@ ><DIV CLASS="example" ><A -NAME="AEN35" +NAME="AEN59" ></A ><P ><B @@ -305,7 +443,7 @@ ><extension name="sample"> <summary>A sample PHP extension</summary> <description> - This is a sample extension speification + This is a sample extension specification showing how to use PECL_Gen for extension generation. </description> @@ -323,13 +461,13 @@ ><HR><H1 CLASS="section" ><A -NAME="AEN38" +NAME="AEN62" ></A >Release information</H1 ><P > The release information for your extension should include the extension authors and maintainers, the version number, state and - release date, the chosen license and maybe a changelog describing + release date, the chosen license and maybe a change log describing previous releases. It is also possible to specify an image file to be used as a product logo with the <TT CLASS="literal" @@ -371,7 +509,7 @@ CLASS="literal" >package.xml</TT > specification so please - refere to the PEAR documentation here for now. + refer to the PEAR documentation here for now. </P ><TABLE WIDTH="100%" @@ -384,7 +522,7 @@ ><DIV CLASS="example" ><A -NAME="AEN47" +NAME="AEN71" ></A ><P ><B @@ -454,7 +592,7 @@ CLASS="literal" >package.xml</TT > counterpart as it is used to - decide which license text should actualy be written to the + decide which license text should actually be written to the <TT CLASS="literal" >LICENSE</TT @@ -489,7 +627,7 @@ ><DIV CLASS="example" ><A -NAME="AEN58" +NAME="AEN82" ></A ><P ><B @@ -555,7 +693,7 @@ ><DIV CLASS="example" ><A -NAME="AEN67" +NAME="AEN91" ></A ><P ><B @@ -585,69 +723,435 @@ ><HR><H1 CLASS="section" ><A -NAME="AEN70" +NAME="AEN94" ></A >Dependencies</H1 ><P -> +> Dependencies are specified within the <B +CLASS="sgmltag" +><</B +><B +CLASS="sgmltag" +>deps</B +><B +CLASS="sgmltag" +>></B +> + environment. Within the <B +CLASS="sgmltag" +><</B +><B +CLASS="sgmltag" +>deps</B +><B +CLASS="sgmltag" +>></B +> itself it is + possible to set the programming language and target platforms using + the <TT +CLASS="literal" +>language=...</TT +> and + <TT +CLASS="literal" +>platform=...</TT +> attributes. </P +><P +> Supported languages are C (<TT +CLASS="literal" +>lang="c"</TT +>) and C++ + (<TT +CLASS="literal" +>language="cpp"</TT +>). The language selection + does not influence code generation itself + (<TT +CLASS="literal" +>pecl-gen</TT +> always generates C code) but the way + extensions are compiled and linked. C++ should only be selected to + interface to external C++ libraries. + </P +><P +> Supported platforms are currently Unix-like systems + (<TT +CLASS="literal" +>platform="unix"</TT +>), Microsoft Windows + (<TT +CLASS="literal" +>platform="win32"</TT +>) or both (<TT +CLASS="literal" +>platform="all"</TT +>). + </P +><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +CLASS="EXAMPLE" +><TR +><TD +><DIV +CLASS="example" +><A +NAME="AEN109" +></A +><P +><B +>Example 2-5. Dependencies</B +></P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +CELLPADDING="5" +><TR +><TD +><PRE +CLASS="programlisting" +>... + <deps language="cpp" platform="win32"> + ... + </deps> +...</PRE +></TD +></TR +></TABLE +></DIV +></TD +></TR +></TABLE ><DIV CLASS="section" ><HR><H2 CLASS="section" ><A -NAME="AEN73" +NAME="AEN112" ></A ><TT CLASS="literal" >--with...</TT ></H2 ><P -> </P +> When building an extension on Unix-like systems or within the + Cygwin environment under Windows the <TT +CLASS="literal" +>configure</TT +> + script will try to figure out where external libraries and header + files needed by an extension are installed on the target system. + Using a "with" option it is possible to specify where to actually + look for libraries and headers. This way it is possible to + override search paths if things are not installed in the default + system paths or to specify the exact version of a package to be + used if multiple versions are installed on the target system. + </P +><P +> The <B +CLASS="sgmltag" +><</B +><B +CLASS="sgmltag" +>with</B +><B +CLASS="sgmltag" +>></B +> tag takes three attributes: + <TT +CLASS="literal" +>name=...</TT +> for the actual name of the "with" + option, <TT +CLASS="literal" +>testfile</TT +> for the relative path of a + file to check for while running the <TT +CLASS="literal" +>configure</TT +> + script and a list of default paths to check if no path is given + as an argument to the "with" option in + <TT +CLASS="literal" +>defaults</TT +>. + </P +><P +> Name and defaults are set to the extension base name and + "/usr:/usr/local" if no values are given. The testfile attribute + is mandatory. + </P +><P +> Textual data enclosed by the <B +CLASS="sgmltag" +><</B +><B +CLASS="sgmltag" +>with</B +><B +CLASS="sgmltag" +>></B +> is used to + describe the "with" option in the output of <TT +CLASS="literal" +>configure + --help</TT +> calls. + </P +><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +CLASS="EXAMPLE" +><TR +><TD +><DIV +CLASS="example" +><A +NAME="AEN127" +></A +><P +><B +>Example 2-6. <TT +CLASS="literal" +>--with...</TT +></B +></P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +CELLPADDING="5" +><TR +><TD +><PRE +CLASS="programlisting" +>... + <with defaults='/usr:/usr/local' testfile='include/sample.h'>sample install</with> +...</PRE +></TD +></TR +></TABLE +></DIV +></TD +></TR +></TABLE ></DIV ><DIV CLASS="section" ><HR><H2 CLASS="section" ><A -NAME="AEN77" +NAME="AEN131" ></A >Libraries</H2 ><P -> </P +> Needed external libraries are specified using the + <B +CLASS="sgmltag" +><</B +><B +CLASS="sgmltag" +>lib</B +><B +CLASS="sgmltag" +>></B +> tag. The <TT +CLASS="literal" +>name=...</TT +> + attribute is mandatory and takes the library base name. A library + dependency by the name "sample" is actually referring to a library + file named <TT +CLASS="filename" +>libsample.a</TT +> for a static or + <TT +CLASS="filename" +>libsample.so</TT +> for a dynamic library on + Unix-like systems or to <TT +CLASS="filename" +>sample.DLL</TT +> on + Windows. + </P +><P +> It is possible to specify the name of a function symbol expected + to be provided by the library using the + <TT +CLASS="literal" +>function=...</TT +> attribute. This function symbol + is being looked for when <TT +CLASS="literal" +>configure</TT +> is run for + the extension. This way it is possible to verify that the right + version of a library was found. With VisualStudio on windows it + is not possible to perform this check, in this case the library + is just added to the project file. + </P +><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +CLASS="EXAMPLE" +><TR +><TD +><DIV +CLASS="example" +><A +NAME="AEN142" +></A +><P +><B +>Example 2-7. Library dependencies</B +></P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +CELLPADDING="5" +><TR +><TD +><PRE +CLASS="programlisting" +>... + <lib name="sample_u" platform="unix" function="sample_v2" /> + <lib name="sample_w" platform="win32" /> + <lib name="sample" platform="all" /> +...</PRE +></TD +></TR +></TABLE +></DIV +></TD +></TR +></TABLE ></DIV ><DIV CLASS="section" ><HR><H2 CLASS="section" ><A -NAME="AEN80" +NAME="AEN145" ></A >Header files</H2 ><P -> </P +> It is possible to specify header files needed by the extension + using the <B +CLASS="sgmltag" +><</B +><B +CLASS="sgmltag" +>header</B +><B +CLASS="sgmltag" +>></B +>. Any headers specified have + to exist in the include path set for compiling (see also the + section on <TT +CLASS="literal" +>--with</TT +> + above). <TT +CLASS="literal" +>#include</TT +> statements for the specified + headers are the last ones to be put into the generated code + unless you set the <TT +CLASS="literal" +>prepend="yes"</TT +> attribute to + have it put in front of the other <TT +CLASS="literal" +>#include</TT +>s. + </P +><DIV +CLASS="note" +><BLOCKQUOTE +CLASS="note" +><P +><B +>Note: </B +> + <TT +CLASS="literal" +>config.m4</TT +>/<TT +CLASS="literal" +>configure</TT +> checks + for header file availability has not been added yet. + </P +></BLOCKQUOTE +></DIV +><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +CLASS="EXAMPLE" +><TR +><TD +><DIV +CLASS="example" +><A +NAME="AEN157" +></A +><P +><B +>Example 2-8. Header file dependencies</B +></P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +CELLPADDING="5" +><TR +><TD +><PRE +CLASS="programlisting" +>... + <header name="include_me_first.h" prepend="yes" /> + <header name="sample.h" /> +...</PRE +></TD +></TR +></TABLE +></DIV +></TD +></TR +></TABLE ></DIV ><DIV CLASS="section" ><HR><H2 CLASS="section" ><A -NAME="AEN83" +NAME="AEN160" ></A >External programs</H2 ><P -> </P +> Not supported yet. + </P ></DIV ><DIV CLASS="section" ><HR><H2 CLASS="section" ><A -NAME="AEN86" +NAME="AEN163" ></A >Other files</H2 ><P -> </P +> Not supported yet. + </P ></DIV ></DIV ><DIV @@ -655,7 +1159,7 @@ ><HR><H1 CLASS="section" ><A -NAME="AEN89" +NAME="AEN166" ></A >Functions</H1 ><P @@ -705,7 +1209,7 @@ ><HR><H2 CLASS="section" ><A -NAME="AEN99" +NAME="AEN176" ></A >Public functions</H2 ><P @@ -889,7 +1393,7 @@ ><HR><H2 CLASS="section" ><A -NAME="AEN140" +NAME="AEN217" ></A >Internal functions</H2 ><P @@ -929,11 +1433,11 @@ ><DIV CLASS="example" ><A -NAME="AEN151" +NAME="AEN228" ></A ><P ><B ->Example 2-5. <TT +>Example 2-9. <TT CLASS="literal" >MINIT()</TT ></B @@ -986,7 +1490,7 @@ ><DD ><P > The request shutdown function. This is called by PHP server - modules before actualy executing a PHP script request or once + modules before actually executing a PHP script request or once right after <TT CLASS="literal" >MINIT()</TT @@ -1004,7 +1508,7 @@ > The request shutdown function. This is called by PHP server modules after execution of PHP code has been finished or terminated. - Is called even if critical PHP errors occured but you can not + Is called even if critical PHP errors occurred but you can not rely on it being called on critical errors or crashes on the C level. </P @@ -1060,11 +1564,11 @@ ><DIV CLASS="example" ><A -NAME="AEN182" +NAME="AEN259" ></A ><P ><B ->Example 2-6. <TT +>Example 2-10. <TT CLASS="literal" >MINFO()</TT ></B @@ -1120,7 +1624,7 @@ ><HR><H2 CLASS="section" ><A -NAME="AEN188" +NAME="AEN265" ></A >Private functions</H2 ><P @@ -1156,7 +1660,7 @@ ><HR><H1 CLASS="section" ><A -NAME="AEN195" +NAME="AEN272" ></A >Constants</H1 ><P @@ -1230,11 +1734,11 @@ ><DIV CLASS="example" ><A -NAME="AEN207" +NAME="AEN284" ></A ><P ><B ->Example 2-7. PHP Constants</B +>Example 2-11. PHP Constants</B ></P ><TABLE BORDER="0" @@ -1270,7 +1774,7 @@ ><HR><H1 CLASS="section" ><A -NAME="AEN210" +NAME="AEN287" ></A ><TT CLASS="literal" @@ -1292,7 +1796,7 @@ > tag. </P ><P -> Module globlals that are only global to a single request need to +> Module globals that are only global to a single request need to be managed to ensure thread safety and initialization on request initialization. <TT CLASS="literal" @@ -1433,7 +1937,7 @@ </P ><P > Directive default values are passed to the engine as strings, so - you may not use any C constats or preprocessor macros here. The + you may not use any C constants or preprocessor macros here. The default value strings are parsed by the <TT CLASS="literal" @@ -1481,7 +1985,7 @@ >system</DT ><DD ><P -> may only be set globaly in <TT +> may only be set globally in <TT CLASS="literal" >php.ini</TT > or the @@ -1537,7 +2041,7 @@ >></B > definitions may also include content data but it is for internal documentation only, it is not - used in DocBooc XML generation (yet). + used in DocBook XML generation (yet). </P ><TABLE WIDTH="100%" @@ -1550,11 +2054,11 @@ ><DIV CLASS="example" ><A -NAME="AEN275" +NAME="AEN352" ></A ><P ><B ->Example 2-8. Globals</B +>Example 2-12. Globals</B ></P ><TABLE BORDER="0" @@ -1588,7 +2092,7 @@ ><HR><H1 CLASS="section" ><A -NAME="AEN278" +NAME="AEN355" ></A >Resources</H1 ><P @@ -1660,7 +2164,7 @@ CLASS="sgmltag" >></B > tag. Within the destructor snippet you - may refere to the allocated payload using the + may refer to the allocated payload using the <TT CLASS="literal" >resource</TT @@ -1699,11 +2203,11 @@ ><DIV CLASS="example" ><A -NAME="AEN297" +NAME="AEN374" ></A ><P ><B ->Example 2-9. Resources</B +>Example 2-13. Resources</B ></P ><TABLE BORDER="0" @@ -1745,7 +2249,7 @@ ><HR><H1 CLASS="section" ><A -NAME="AEN300" +NAME="AEN377" ></A >Classes</H1 ><P @@ -1757,7 +2261,7 @@ ><HR><H1 CLASS="section" ><A -NAME="AEN303" +NAME="AEN380" ></A >Streams</H1 ><P @@ -1769,11 +2273,11 @@ ><HR><H1 CLASS="section" ><A -NAME="AEN306" +NAME="AEN383" ></A >Custom code</H1 ><P -> Custum code may be added to your extension source files using the +> Custom code may be added to your extension source files using the <B CLASS="sgmltag" ><</B @@ -1830,7 +2334,7 @@ ><HR><H1 CLASS="section" ><A -NAME="AEN319" +NAME="AEN396" ></A >Tests</H1 ><P
Index: pear/PECL_Gen/manual.xml diff -u pear/PECL_Gen/manual.xml:1.1 pear/PECL_Gen/manual.xml:1.2 --- pear/PECL_Gen/manual.xml:1.1 Fri Jul 11 04:36:07 2003 +++ pear/PECL_Gen/manual.xml Sat Jul 12 03:16:18 2003 @@ -16,7 +16,7 @@ configuration file. </para> <para> - It also supports the simpler (but less powerfull) prototype file + It also supports the simpler (but less powerful) prototype file format as used by the shell script <literal>ext_skel</literal> that is part of the PHP source code. </para> @@ -33,15 +33,85 @@ <section> <title>Features</title> <para> - + <literal>pecl-gen</literal> tries to support as many extension + writing aspects as possible. This currently includes code and documentation + generation for: + <simplelist> + <member>functions</member> + <member>constants</member> + <member><literal>php.ini</literal> configuration directives</member> + <member>resource types</member> + <member>per-thread global variables</member> + </simplelist> + </para> + <para> + <literal>pecl-gen</literal> also generates + <filename>config.m4</filename> + configuration files for Unix-like build environments, + VisualStudio <filename>*.dsp</filename> project files for Windows + and the <filename>package.xml</filename> files needed for + PEAR/PECL packaging. + </para> + <para> + DocBook XML documentation templates suitable for inclusion in the + PHP or PEAR manual is generated in the hope that it will ease the + task of documenting extension. + </para> + <para> + Test scripts for automatic regression testing are already created + but due to some missing features within the "<literal>make + test</literal>" infrastructure it is not possible to use the + generated tests with standalone PECL extensions right now. </para> </section> <section> <title>How to use it</title> <para> - - </para> + There are currently three different modes of operation for + <literal>pecl-gen</literal>. In its default mode it can create a complete + ready-to-compile extension from an XML description (documented in + the next chapter). In <literal>ext_skel</literal> compatibility + mode it generates the extension from some command line parameters + and an optional function prototype file and in immediate mode it + just takes a function prototype from command line and writes a + C code skeleton for just that function to standard output. + </para> + <para> + <literal>ext_skel</literal> compatibility mode is not documented + here, please refer to the original <literal>ext_skel</literal> + documentation instead. + </para> + <para> + Below you find a hardcopy of the <literal>pecl-gen + --help</literal> output: + </para> + <screen> +pecl-gen [-h] [--extname=name] [--proto=file] [--skel=dir] [--stubs=file] + [--no-help] [--xml[=file]] [--full-xml] [--function=proto] [specfile.xml] + + -h|--help this message + --force overwrite existing directories + --function create a function skeleton from a proto right away + --version show version info + + the following options are inherited from ext_skel: + + --extname=module module is the name of your extension + --proto=file file contains prototypes of functions to create + --xml generate xml documentation to be added to phpdoc-cvs + + these wait for functionality to be implemented and are ignored for now ... + --stubs=file generate only function stubs in file + --no-help don't try to be nice and create comments in the code + and helper functions to test if the module compiled + + these are accepted for backwards compatibility reasons but not used ... + --full-xml generate xml documentation for a self-contained extension + (this was also a no-op in ext_skel) + --skel=dir path to the skeleton directory + (skeleton stuff is now self-contained) + </screen> </section> </chapter> @@ -54,16 +124,16 @@ <para> The top level container tag describing an extension is the <sgmltag>extension</sgmltag> tag. The name of the extension - is given in the <literal>name</literal> attibute. The extension + is given in the <literal>name</literal> attribute. The extension name has to be a valid C name as it is used as both the extensions - directory name and the basename for several C symbols within the + directory name and the base name for several C symbols within the generated C code. </para> <para> The tags <sgmltag>summary</sgmltag> and <sgmltag>description</sgmltag> should be added at the very top of - your extesnions. The summary should be a short one-line - description of the extension while the actualy description can be + your extensions. The summary should be a short one-line + description of the extension while the actually description can be as detailed as you like. Both are later used to generate the <literal>package.xml</literal> file and the documentation for your extension. The summary line is also put into the @@ -76,7 +146,7 @@ <extension name="sample"> <summary>A sample PHP extension</summary> <description> - This is a sample extension speification + This is a sample extension specification showing how to use PECL_Gen for extension generation. </description> @@ -91,7 +161,7 @@ <para> The release information for your extension should include the extension authors and maintainers, the version number, state and - release date, the chosen license and maybe a changelog describing + release date, the chosen license and maybe a change log describing previous releases. It is also possible to specify an image file to be used as a product logo with the <literal>phpinfo()</literal> output block for the extension. @@ -100,7 +170,7 @@ The <sgmltag>maintainers</sgmltag>, <sgmltag>release</sgmltag> and <sgmltag>changelog</sgmltag> tags specifications are taken from the PEAR <literal>package.xml</literal> specification so please - refere to the PEAR documentation here for now. + refer to the PEAR documentation here for now. </para> <example> <title>Release information</title> @@ -146,7 +216,7 @@ <para> The <sgmltag>license</sgmltag> tag is a little more restrictive as its <literal>package.xml</literal> counterpart as it is used to - decide which license text should actualy be written to the + decide which license text should actually be written to the <literal>LICENSE</literal>. For now you have to specify either <literal>PHP</literal>, <literal>BSD</literal> or <literal>LGPL</literal>, any other value is taken as @@ -189,29 +259,120 @@ <para> Dependencies are specified within the <sgmltag>deps</sgmltag> environment. Within the <sgmltag>deps</sgmltag> itself it is - possible to set the programing language and target platforms using + possible to set the programming language and target platforms using the <literal>language=...</literal> and <literal>platform=...</literal> attributes. </para> <para> + Supported languages are C (<literal>lang="c"</literal>) and C++ + (<literal>language="cpp"</literal>). The language selection + does not influence code generation itself + (<literal>pecl-gen</literal> always generates C code) but the way + extensions are compiled and linked. C++ should only be selected to + interface to external C++ libraries. </para> + <para> + Supported platforms are currently Unix-like systems + (<literal>platform="unix"</literal>), Microsoft Windows + (<literal>platform="win32"</literal>) or both (<literal>platform="all"</literal>). + </para> + <example> + <title>Dependencies</title> + <programlisting> +<![CDATA[ +... + <deps language="cpp" platform="win32"> + ... + </deps> +... +]]> + </programlisting> + </example> <section> <title><literal>--with...</literal></title> <para> - </para> + When building an extension on Unix-like systems or within the + Cygwin environment under Windows the <literal>configure</literal> + script will try to figure out where external libraries and header + files needed by an extension are installed on the target system. + Using a "with" option it is possible to specify where to actually + look for libraries and headers. This way it is possible to + override search paths if things are not installed in the default + system paths or to specify the exact version of a package to be + used if multiple versions are installed on the target system. + </para> + <para> + The <sgmltag>with</sgmltag> tag takes three attributes: + <literal>name=...</literal> for the actual name of the "with" + option, <literal>testfile</literal> for the relative path of a + file to check for while running the <literal>configure</literal> + script and a list of default paths to check if no path is given + as an argument to the "with" option in + <literal>defaults</literal>. + </para> + <para> + Name and defaults are set to the extension base name and + "/usr:/usr/local" if no values are given. The testfile attribute + is mandatory. + </para> + <para> + Textual data enclosed by the <sgmltag>with</sgmltag> is used to + describe the "with" option in the output of <literal>configure + --help</literal> calls. + </para> + <example> + <title><literal>--with...</literal></title> + <programlisting> +<![CDATA[ +... + <with defaults='/usr:/usr/local' testfile='include/sample.h'>sample install</with> +... +]]> + </programlisting> + </example> </section> <section> <title>Libraries</title> <para> - </para> + Needed external libraries are specified using the + <sgmltag>lib</sgmltag> tag. The <literal>name=...</literal> + attribute is mandatory and takes the library base name. A library + dependency by the name "sample" is actually referring to a library + file named <filename>libsample.a</filename> for a static or + <filename>libsample.so</filename> for a dynamic library on + Unix-like systems or to <filename>sample.DLL</filename> on + Windows. + </para> + <para> + It is possible to specify the name of a function symbol expected + to be provided by the library using the + <literal>function=...</literal> attribute. This function symbol + is being looked for when <literal>configure</literal> is run for + the extension. This way it is possible to verify that the right + version of a library was found. With VisualStudio on windows it + is not possible to perform this check, in this case the library + is just added to the project file. + </para> + <example> + <title>Library dependencies</title> + <programlisting> +<![CDATA[ +... + <lib name="sample_u" platform="unix" function="sample_v2" /> + <lib name="sample_w" platform="win32" /> + <lib name="sample" platform="all" /> +... +]]> + </programlisting> + </example> </section> <section> <title>Header files</title> <para> - It is possible to speify header files needed by the extension + It is possible to specify header files needed by the extension using the <sgmltag>header</sgmltag>. Any headers specified have to exist in the include path set for compiling (see also the section on <literal>--with</literal> @@ -226,6 +387,17 @@ for header file availability has not been added yet. </para> </note> + <example> + <title>Header file dependencies</title> + <programlisting> +<![CDATA[ +... + <header name="include_me_first.h" prepend="yes" /> + <header name="sample.h" /> +... +]]> + </programlisting> + </example> </section> <section> @@ -373,7 +545,7 @@ <listitem> <simpara> The request shutdown function. This is called by PHP server - modules before actualy executing a PHP script request or once + modules before actually executing a PHP script request or once right after <literal>MINIT()</literal> for standalone binaries (CGI or CLI). </simpara> @@ -386,7 +558,7 @@ The request shutdown function. This is called by PHP server modules after execution of PHP code has been finished or terminated. - Is called even if critical PHP errors occured but you can not + Is called even if critical PHP errors occurred but you can not rely on it being called on critical errors or crashes on the C level. </simpara> @@ -504,7 +676,7 @@ they can be defined using C code within the <sgmltag>code</sgmltag> tag. </para> <para> - Module globlals that are only global to a single request need to + Module globals that are only global to a single request need to be managed to ensure thread safety and initialization on request initialization. <literal>php.ini</literal> directive values are also stored as module globals but need some additional definitions. @@ -552,7 +724,7 @@ </para> <para> Directive default values are passed to the engine as strings, so - you may not use any C constats or preprocessor macros here. The + you may not use any C constants or preprocessor macros here. The default value strings are parsed by the <literal>OnUpdate</literal> handler registered for that directive. No value checking takes place during extension code @@ -572,7 +744,7 @@ <term>system</term> <listitem> <para> - may only be set globaly in <literal>php.ini</literal> or the + may only be set globally in <literal>php.ini</literal> or the web server configuration </para> </listitem> @@ -598,7 +770,7 @@ generate documentation for the defined directive. <sgmltag>global</sgmltag> definitions may also include content data but it is for internal documentation only, it is not - used in DocBooc XML generation (yet). + used in DocBook XML generation (yet). </para> <example> <title>Globals</title> @@ -646,7 +818,7 @@ payload needs to be cleaned up as well you have to add an appropriate C code snippet that takes care of this using the <sgmltag>destruct</sgmltag> tag. Within the destructor snippet you - may refere to the allocated payload using the + may refer to the allocated payload using the <literal>resource</literal> pointer variable. </para> <para> @@ -704,7 +876,7 @@ <section> <title>Custom code</title> <para> - Custum code may be added to your extension source files using the + Custom code may be added to your extension source files using the <sgmltag>code</sgmltag> tags. The <literal>role=...</literal> and <literal>position=...</literal> tags specify the actual place in there generated source files where your code should be Index: pear/PECL_Gen/manual.html diff -u pear/PECL_Gen/manual.html:1.1 pear/PECL_Gen/manual.html:1.2 --- pear/PECL_Gen/manual.html:1.1 Fri Jul 11 04:36:07 2003 +++ pear/PECL_Gen/manual.html Sat Jul 12 03:16:18 2003 @@ -57,46 +57,46 @@ ></DT ><DT ><A -HREF="#AEN20" +HREF="#AEN36" >How to use it</A ></DT ></DL ></DD ><DT >2. <A -HREF="#AEN23" +HREF="#AEN47" >The XML description</A ></DT ><DD ><DL ><DT ><A -HREF="#AEN25" +HREF="#AEN49" >Basics</A ></DT ><DT ><A -HREF="#AEN38" +HREF="#AEN62" >Release information</A ></DT ><DT ><A -HREF="#AEN70" +HREF="#AEN94" >Dependencies</A ></DT ><DT ><A -HREF="#AEN89" +HREF="#AEN166" >Functions</A ></DT ><DT ><A -HREF="#AEN195" +HREF="#AEN272" >Constants</A ></DT ><DT ><A -HREF="#AEN210" +HREF="#AEN287" ><TT CLASS="literal" >php.ini</TT @@ -104,27 +104,27 @@ ></DT ><DT ><A -HREF="#AEN278" +HREF="#AEN355" >Resources</A ></DT ><DT ><A -HREF="#AEN300" +HREF="#AEN377" >Classes</A ></DT ><DT ><A -HREF="#AEN303" +HREF="#AEN380" >Streams</A ></DT ><DT ><A -HREF="#AEN306" +HREF="#AEN383" >Custom code</A ></DT ><DT ><A -HREF="#AEN319" +HREF="#AEN396" >Tests</A ></DT ></DL @@ -155,7 +155,7 @@ configuration file. </P ><P -> It also supports the simpler (but less powerfull) prototype file +> It also supports the simpler (but less powerful) prototype file format as used by the shell script <TT CLASS="literal" >ext_skel</TT @@ -192,7 +192,79 @@ ></A >Features</H1 ><P -> +> <TT +CLASS="literal" +>pecl-gen</TT +> tries to support as many extension + writing aspects as possible. This currently includes code and documentation + generation for: + <P +></P +><TABLE +BORDER="0" +><TBODY +><TR +><TD +>functions</TD +></TR +><TR +><TD +>constants</TD +></TR +><TR +><TD +><TT +CLASS="literal" +>php.ini</TT +> configuration directives</TD +></TR +><TR +><TD +>resource types</TD +></TR +><TR +><TD +>per-thread global variables</TD +></TR +></TBODY +></TABLE +><P +></P +> + </P +><P +> <TT +CLASS="literal" +>pecl-gen</TT +> also generates + <TT +CLASS="filename" +>config.m4</TT +> + configuration files for Unix-like build environments, + VisualStudio <TT +CLASS="filename" +>*.dsp</TT +> project files for Windows + and the <TT +CLASS="filename" +>package.xml</TT +> files needed for + PEAR/PECL packaging. + </P +><P +> DocBook XML documentation templates suitable for inclusion in the + PHP or PEAR manual is generated in the hope that it will ease the + task of documenting extension. + </P +><P +> Test scripts for automatic regression testing are already created + but due to some missing features within the "<TT +CLASS="literal" +>make + test</TT +>" infrastructure it is not possible to use the + generated tests with standalone PECL extensions right now. </P ></DIV ><DIV @@ -200,19 +272,85 @@ ><HR><H1 CLASS="section" ><A -NAME="AEN20" +NAME="AEN36" ></A >How to use it</H1 ><P -> +> There are currently three different modes of operation for + <TT +CLASS="literal" +>pecl-gen</TT +>. In its default mode it can create a complete + ready-to-compile extension from an XML description (documented in + the next chapter). In <TT +CLASS="literal" +>ext_skel</TT +> compatibility + mode it generates the extension from some command line parameters + and an optional function prototype file and in immediate mode it + just takes a function prototype from command line and writes a + C code skeleton for just that function to standard output. + </P +><P +> <TT +CLASS="literal" +>ext_skel</TT +> compatibility mode is not documented + here, please refer to the original <TT +CLASS="literal" +>ext_skel</TT +> + documentation instead. </P +><P +> Below you find a hardcopy of the <TT +CLASS="literal" +>pecl-gen + --help</TT +> output: + </P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +CELLPADDING="5" +><TR +><TD +><PRE +CLASS="screen" +>pecl-gen [-h] [--extname=name] [--proto=file] [--skel=dir] [--stubs=file] + [--no-help] [--xml[=file]] [--full-xml] [--function=proto] [specfile.xml] + + -h|--help this message + --force overwrite existing directories + --function create a function skeleton from a proto right away + --version show version info + + the following options are inherited from ext_skel: + + --extname=module module is the name of your extension + --proto=file file contains prototypes of functions to create + --xml generate xml documentation to be added to phpdoc-cvs + + these wait for functionality to be implemented and are ignored for now ... + --stubs=file generate only function stubs in file + --no-help don't try to be nice and create comments in the code + and helper functions to test if the module compiled + + these are accepted for backwards compatibility reasons but not used ... + --full-xml generate xml documentation for a self-contained extension + (this was also a no-op in ext_skel) + --skel=dir path to the skeleton directory + (skeleton stuff is now self-contained)</PRE +></TD +></TR +></TABLE ></DIV ></DIV ><DIV CLASS="chapter" ><HR><H1 ><A -NAME="AEN23" +NAME="AEN47" >Chapter 2. The XML description</A ></H1 ><DIV @@ -220,7 +358,7 @@ ><H1 CLASS="section" ><A -NAME="AEN25" +NAME="AEN49" ></A >Basics</H1 ><P @@ -238,9 +376,9 @@ is given in the <TT CLASS="literal" >name</TT -> attibute. The extension +> attribute. The extension name has to be a valid C name as it is used as both the extensions - directory name and the basename for several C symbols within the + directory name and the base name for several C symbols within the generated C code. </P ><P @@ -264,8 +402,8 @@ CLASS="sgmltag" >></B > should be added at the very top of - your extesnions. The summary should be a short one-line - description of the extension while the actualy description can be + your extensions. The summary should be a short one-line + description of the extension while the actually description can be as detailed as you like. Both are later used to generate the <TT CLASS="literal" @@ -288,7 +426,7 @@ ><DIV CLASS="example" ><A -NAME="AEN35" +NAME="AEN59" ></A ><P ><B @@ -305,7 +443,7 @@ ><extension name="sample"> <summary>A sample PHP extension</summary> <description> - This is a sample extension speification + This is a sample extension specification showing how to use PECL_Gen for extension generation. </description> @@ -323,13 +461,13 @@ ><HR><H1 CLASS="section" ><A -NAME="AEN38" +NAME="AEN62" ></A >Release information</H1 ><P > The release information for your extension should include the extension authors and maintainers, the version number, state and - release date, the chosen license and maybe a changelog describing + release date, the chosen license and maybe a change log describing previous releases. It is also possible to specify an image file to be used as a product logo with the <TT CLASS="literal" @@ -371,7 +509,7 @@ CLASS="literal" >package.xml</TT > specification so please - refere to the PEAR documentation here for now. + refer to the PEAR documentation here for now. </P ><TABLE WIDTH="100%" @@ -384,7 +522,7 @@ ><DIV CLASS="example" ><A -NAME="AEN47" +NAME="AEN71" ></A ><P ><B @@ -454,7 +592,7 @@ CLASS="literal" >package.xml</TT > counterpart as it is used to - decide which license text should actualy be written to the + decide which license text should actually be written to the <TT CLASS="literal" >LICENSE</TT @@ -489,7 +627,7 @@ ><DIV CLASS="example" ><A -NAME="AEN58" +NAME="AEN82" ></A ><P ><B @@ -555,7 +693,7 @@ ><DIV CLASS="example" ><A -NAME="AEN67" +NAME="AEN91" ></A ><P ><B @@ -585,69 +723,435 @@ ><HR><H1 CLASS="section" ><A -NAME="AEN70" +NAME="AEN94" ></A >Dependencies</H1 ><P -> +> Dependencies are specified within the <B +CLASS="sgmltag" +><</B +><B +CLASS="sgmltag" +>deps</B +><B +CLASS="sgmltag" +>></B +> + environment. Within the <B +CLASS="sgmltag" +><</B +><B +CLASS="sgmltag" +>deps</B +><B +CLASS="sgmltag" +>></B +> itself it is + possible to set the programming language and target platforms using + the <TT +CLASS="literal" +>language=...</TT +> and + <TT +CLASS="literal" +>platform=...</TT +> attributes. </P +><P +> Supported languages are C (<TT +CLASS="literal" +>lang="c"</TT +>) and C++ + (<TT +CLASS="literal" +>language="cpp"</TT +>). The language selection + does not influence code generation itself + (<TT +CLASS="literal" +>pecl-gen</TT +> always generates C code) but the way + extensions are compiled and linked. C++ should only be selected to + interface to external C++ libraries. + </P +><P +> Supported platforms are currently Unix-like systems + (<TT +CLASS="literal" +>platform="unix"</TT +>), Microsoft Windows + (<TT +CLASS="literal" +>platform="win32"</TT +>) or both (<TT +CLASS="literal" +>platform="all"</TT +>). + </P +><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +CLASS="EXAMPLE" +><TR +><TD +><DIV +CLASS="example" +><A +NAME="AEN109" +></A +><P +><B +>Example 2-5. Dependencies</B +></P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +CELLPADDING="5" +><TR +><TD +><PRE +CLASS="programlisting" +>... + <deps language="cpp" platform="win32"> + ... + </deps> +...</PRE +></TD +></TR +></TABLE +></DIV +></TD +></TR +></TABLE ><DIV CLASS="section" ><HR><H2 CLASS="section" ><A -NAME="AEN73" +NAME="AEN112" ></A ><TT CLASS="literal" >--with...</TT ></H2 ><P -> </P +> When building an extension on Unix-like systems or within the + Cygwin environment under Windows the <TT +CLASS="literal" +>configure</TT +> + script will try to figure out where external libraries and header + files needed by an extension are installed on the target system. + Using a "with" option it is possible to specify where to actually + look for libraries and headers. This way it is possible to + override search paths if things are not installed in the default + system paths or to specify the exact version of a package to be + used if multiple versions are installed on the target system. + </P +><P +> The <B +CLASS="sgmltag" +><</B +><B +CLASS="sgmltag" +>with</B +><B +CLASS="sgmltag" +>></B +> tag takes three attributes: + <TT +CLASS="literal" +>name=...</TT +> for the actual name of the "with" + option, <TT +CLASS="literal" +>testfile</TT +> for the relative path of a + file to check for while running the <TT +CLASS="literal" +>configure</TT +> + script and a list of default paths to check if no path is given + as an argument to the "with" option in + <TT +CLASS="literal" +>defaults</TT +>. + </P +><P +> Name and defaults are set to the extension base name and + "/usr:/usr/local" if no values are given. The testfile attribute + is mandatory. + </P +><P +> Textual data enclosed by the <B +CLASS="sgmltag" +><</B +><B +CLASS="sgmltag" +>with</B +><B +CLASS="sgmltag" +>></B +> is used to + describe the "with" option in the output of <TT +CLASS="literal" +>configure + --help</TT +> calls. + </P +><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +CLASS="EXAMPLE" +><TR +><TD +><DIV +CLASS="example" +><A +NAME="AEN127" +></A +><P +><B +>Example 2-6. <TT +CLASS="literal" +>--with...</TT +></B +></P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +CELLPADDING="5" +><TR +><TD +><PRE +CLASS="programlisting" +>... + <with defaults='/usr:/usr/local' testfile='include/sample.h'>sample install</with> +...</PRE +></TD +></TR +></TABLE +></DIV +></TD +></TR +></TABLE ></DIV ><DIV CLASS="section" ><HR><H2 CLASS="section" ><A -NAME="AEN77" +NAME="AEN131" ></A >Libraries</H2 ><P -> </P +> Needed external libraries are specified using the + <B +CLASS="sgmltag" +><</B +><B +CLASS="sgmltag" +>lib</B +><B +CLASS="sgmltag" +>></B +> tag. The <TT +CLASS="literal" +>name=...</TT +> + attribute is mandatory and takes the library base name. A library + dependency by the name "sample" is actually referring to a library + file named <TT +CLASS="filename" +>libsample.a</TT +> for a static or + <TT +CLASS="filename" +>libsample.so</TT +> for a dynamic library on + Unix-like systems or to <TT +CLASS="filename" +>sample.DLL</TT +> on + Windows. + </P +><P +> It is possible to specify the name of a function symbol expected + to be provided by the library using the + <TT +CLASS="literal" +>function=...</TT +> attribute. This function symbol + is being looked for when <TT +CLASS="literal" +>configure</TT +> is run for + the extension. This way it is possible to verify that the right + version of a library was found. With VisualStudio on windows it + is not possible to perform this check, in this case the library + is just added to the project file. + </P +><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +CLASS="EXAMPLE" +><TR +><TD +><DIV +CLASS="example" +><A +NAME="AEN142" +></A +><P +><B +>Example 2-7. Library dependencies</B +></P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +CELLPADDING="5" +><TR +><TD +><PRE +CLASS="programlisting" +>... + <lib name="sample_u" platform="unix" function="sample_v2" /> + <lib name="sample_w" platform="win32" /> + <lib name="sample" platform="all" /> +...</PRE +></TD +></TR +></TABLE +></DIV +></TD +></TR +></TABLE ></DIV ><DIV CLASS="section" ><HR><H2 CLASS="section" ><A -NAME="AEN80" +NAME="AEN145" ></A >Header files</H2 ><P -> </P +> It is possible to specify header files needed by the extension + using the <B +CLASS="sgmltag" +><</B +><B +CLASS="sgmltag" +>header</B +><B +CLASS="sgmltag" +>></B +>. Any headers specified have + to exist in the include path set for compiling (see also the + section on <TT +CLASS="literal" +>--with</TT +> + above). <TT +CLASS="literal" +>#include</TT +> statements for the specified + headers are the last ones to be put into the generated code + unless you set the <TT +CLASS="literal" +>prepend="yes"</TT +> attribute to + have it put in front of the other <TT +CLASS="literal" +>#include</TT +>s. + </P +><DIV +CLASS="note" +><BLOCKQUOTE +CLASS="note" +><P +><B +>Note: </B +> + <TT +CLASS="literal" +>config.m4</TT +>/<TT +CLASS="literal" +>configure</TT +> checks + for header file availability has not been added yet. + </P +></BLOCKQUOTE +></DIV +><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +CLASS="EXAMPLE" +><TR +><TD +><DIV +CLASS="example" +><A +NAME="AEN157" +></A +><P +><B +>Example 2-8. Header file dependencies</B +></P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +CELLPADDING="5" +><TR +><TD +><PRE +CLASS="programlisting" +>... + <header name="include_me_first.h" prepend="yes" /> + <header name="sample.h" /> +...</PRE +></TD +></TR +></TABLE +></DIV +></TD +></TR +></TABLE ></DIV ><DIV CLASS="section" ><HR><H2 CLASS="section" ><A -NAME="AEN83" +NAME="AEN160" ></A >External programs</H2 ><P -> </P +> Not supported yet. + </P ></DIV ><DIV CLASS="section" ><HR><H2 CLASS="section" ><A -NAME="AEN86" +NAME="AEN163" ></A >Other files</H2 ><P -> </P +> Not supported yet. + </P ></DIV ></DIV ><DIV @@ -655,7 +1159,7 @@ ><HR><H1 CLASS="section" ><A -NAME="AEN89" +NAME="AEN166" ></A >Functions</H1 ><P @@ -705,7 +1209,7 @@ ><HR><H2 CLASS="section" ><A -NAME="AEN99" +NAME="AEN176" ></A >Public functions</H2 ><P @@ -889,7 +1393,7 @@ ><HR><H2 CLASS="section" ><A -NAME="AEN140" +NAME="AEN217" ></A >Internal functions</H2 ><P @@ -929,11 +1433,11 @@ ><DIV CLASS="example" ><A -NAME="AEN151" +NAME="AEN228" ></A ><P ><B ->Example 2-5. <TT +>Example 2-9. <TT CLASS="literal" >MINIT()</TT ></B @@ -986,7 +1490,7 @@ ><DD ><P > The request shutdown function. This is called by PHP server - modules before actualy executing a PHP script request or once + modules before actually executing a PHP script request or once right after <TT CLASS="literal" >MINIT()</TT @@ -1004,7 +1508,7 @@ > The request shutdown function. This is called by PHP server modules after execution of PHP code has been finished or terminated. - Is called even if critical PHP errors occured but you can not + Is called even if critical PHP errors occurred but you can not rely on it being called on critical errors or crashes on the C level. </P @@ -1060,11 +1564,11 @@ ><DIV CLASS="example" ><A -NAME="AEN182" +NAME="AEN259" ></A ><P ><B ->Example 2-6. <TT +>Example 2-10. <TT CLASS="literal" >MINFO()</TT ></B @@ -1120,7 +1624,7 @@ ><HR><H2 CLASS="section" ><A -NAME="AEN188" +NAME="AEN265" ></A >Private functions</H2 ><P @@ -1156,7 +1660,7 @@ ><HR><H1 CLASS="section" ><A -NAME="AEN195" +NAME="AEN272" ></A >Constants</H1 ><P @@ -1230,11 +1734,11 @@ ><DIV CLASS="example" ><A -NAME="AEN207" +NAME="AEN284" ></A ><P ><B ->Example 2-7. PHP Constants</B +>Example 2-11. PHP Constants</B ></P ><TABLE BORDER="0" @@ -1270,7 +1774,7 @@ ><HR><H1 CLASS="section" ><A -NAME="AEN210" +NAME="AEN287" ></A ><TT CLASS="literal" @@ -1292,7 +1796,7 @@ > tag. </P ><P -> Module globlals that are only global to a single request need to +> Module globals that are only global to a single request need to be managed to ensure thread safety and initialization on request initialization. <TT CLASS="literal" @@ -1433,7 +1937,7 @@ </P ><P > Directive default values are passed to the engine as strings, so - you may not use any C constats or preprocessor macros here. The + you may not use any C constants or preprocessor macros here. The default value strings are parsed by the <TT CLASS="literal" @@ -1481,7 +1985,7 @@ >system</DT ><DD ><P -> may only be set globaly in <TT +> may only be set globally in <TT CLASS="literal" >php.ini</TT > or the @@ -1537,7 +2041,7 @@ >></B > definitions may also include content data but it is for internal documentation only, it is not - used in DocBooc XML generation (yet). + used in DocBook XML generation (yet). </P ><TABLE WIDTH="100%" @@ -1550,11 +2054,11 @@ ><DIV CLASS="example" ><A -NAME="AEN275" +NAME="AEN352" ></A ><P ><B ->Example 2-8. Globals</B +>Example 2-12. Globals</B ></P ><TABLE BORDER="0" @@ -1588,7 +2092,7 @@ ><HR><H1 CLASS="section" ><A -NAME="AEN278" +NAME="AEN355" ></A >Resources</H1 ><P @@ -1660,7 +2164,7 @@ CLASS="sgmltag" >></B > tag. Within the destructor snippet you - may refere to the allocated payload using the + may refer to the allocated payload using the <TT CLASS="literal" >resource</TT @@ -1699,11 +2203,11 @@ ><DIV CLASS="example" ><A -NAME="AEN297" +NAME="AEN374" ></A ><P ><B ->Example 2-9. Resources</B +>Example 2-13. Resources</B ></P ><TABLE BORDER="0" @@ -1745,7 +2249,7 @@ ><HR><H1 CLASS="section" ><A -NAME="AEN300" +NAME="AEN377" ></A >Classes</H1 ><P @@ -1757,7 +2261,7 @@ ><HR><H1 CLASS="section" ><A -NAME="AEN303" +NAME="AEN380" ></A >Streams</H1 ><P @@ -1769,11 +2273,11 @@ ><HR><H1 CLASS="section" ><A -NAME="AEN306" +NAME="AEN383" ></A >Custom code</H1 ><P -> Custum code may be added to your extension source files using the +> Custom code may be added to your extension source files using the <B CLASS="sgmltag" ><</B @@ -1830,7 +2334,7 @@ ><HR><H1 CLASS="section" ><A -NAME="AEN319" +NAME="AEN396" ></A >Tests</H1 ><P