mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-15 16:38:54 +00:00
- Finish DocBook5 updates in internals
- Add new content for internals2.structure section (bjori: new IDs internals2.structure.[files|globals|lifecycle|modstruct|tests]) - Add a few entities to globals.ent for commonly repeated links - Resurrect comments from manual.xml.in for informational purposes git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@238169 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Gwynne Raskind
parent
9ad4e3b55f
commit
08faf26269
7 changed files with 297 additions and 3 deletions
|
|
@ -1,5 +1,23 @@
|
|||
<?xml version="1.0" encoding="ISO-8859-1"?>
|
||||
<!-- $Revision: 1.2 $ -->
|
||||
<!-- $Revision: 1.3 $ -->
|
||||
|
||||
<!--
|
||||
&internals2.buildsys.index; configure options, ext_skel, config.m4, config.w32, static vs. dynamic builds
|
||||
&internals2.structure.index; ext_skel, module structure, globals, lifecycle, tests
|
||||
&internals2.memory.index; management, persistence, TSRM
|
||||
&internals2.variables.index; zval, hashtable, references, constants
|
||||
&internals2.funcs.index; defining, arguments, return values, passthru, aliasing, exceptions
|
||||
&internals2.objects.index; classes, inheritance, properties, methods, method-function mapping
|
||||
&internals2.resources.index; defining, creating, retrieving, destroying
|
||||
&internals2.ini.index; defining, retrieving, changing
|
||||
&internals2.streams.index; using, wrappers, contexts, filters
|
||||
&internals2.pdo.index; direct port of existing PDO docs
|
||||
&internals2.faq.index; FAQ
|
||||
&internals2.apiref.index; full index of all APIs, constants, macros, etc.
|
||||
&internals2.ze1.index; old docs, quick list of major differences, short discussion re: OOP
|
||||
&internals2.ze3.index; quick discussion of major changes, some details on Unicode
|
||||
-->
|
||||
|
||||
<partintro xmlns="http://docbook.org/ns/docbook">
|
||||
<para>
|
||||
The Zend API has evolved considerably over time, as PHP has become a more
|
||||
|
|
|
|||
153
internals2/structure/files.xml
Normal file
153
internals2/structure/files.xml
Normal file
|
|
@ -0,0 +1,153 @@
|
|||
<?xml version="1.0" encoding="ISO-8859-1" ?>
|
||||
<!-- $Revision: 1.1 $ -->
|
||||
<sect1 xml:id="internals2.structure.files" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
<title>Files which make up an extension</title>
|
||||
<para>
|
||||
Whether created by hand, using <command>ext_skel</command>, or by an
|
||||
alternate extension generator, such as
|
||||
<link xlink:href="http://codegenerators.php-baustelle.de/">CodeGen</link>,
|
||||
all extensions will have at least four files:
|
||||
</para>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><filename>config.m4</filename></term>
|
||||
<listitem>
|
||||
<para>
|
||||
UNIX build system configuration (see
|
||||
<xref linkend="internals2.buildsys.configunix"/>)
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><filename>config.w32</filename></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Windows buildsystem configuration (see
|
||||
<xref linkend="internals2.buildsys.configwin"/>)
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><filename>php_example.h</filename></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Main extension header file. By convention, the name of this file is
|
||||
<literal>php_</literal> prepended to the extension name, but this is not
|
||||
a requirement. This file contains macros, prototypes, and globals, just
|
||||
like any header.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><filename>example.c</filename></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Main extension source file. Again by convention, this name of this file
|
||||
is the extension name, but again this is not a requirement. This file
|
||||
contains the module structure declaration, INI entries, management
|
||||
functions, userspace functions, and other requirements of an extension.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
<para>
|
||||
The buildsystem files are discussed elsewhere; this section concentrates on
|
||||
the rest. These four files make up the bare minimum for an extension, which
|
||||
may also contain any number of headers, source files, unit tests, and other
|
||||
support files. The list of files in a realistic extension might look like
|
||||
this:
|
||||
</para>
|
||||
|
||||
<example xml:id="internals2.structure.files.ex1">
|
||||
<title>Files in an example "real" extension, in no particular order</title>
|
||||
<screen>
|
||||
<![CDATA[
|
||||
ext/
|
||||
example/
|
||||
.cvsignore
|
||||
config.m4
|
||||
config.w32
|
||||
example_util.h
|
||||
example_util.c
|
||||
php_example.h
|
||||
example.c
|
||||
package.xml
|
||||
CREDITS
|
||||
tests/
|
||||
critical_function_001.phpt
|
||||
critical_function_002.phpt
|
||||
optional_function_001.phpt
|
||||
optional_function_002.phpt
|
||||
]]>
|
||||
</screen>
|
||||
</example>
|
||||
|
||||
<sect2 xml:id="internals2.structure.files.misc-files">
|
||||
<title>Non-source files</title>
|
||||
<para>
|
||||
The <filename>.cvsignore</filename> file is used for extensions which are
|
||||
checked into one of the PHP <command>CVS</command> repositories (usually
|
||||
&link.pecl;); the one generated by <command>ext_skel</command> contains:
|
||||
</para>
|
||||
|
||||
<informalexample>
|
||||
<programlisting role="cvsignore">
|
||||
<![CDATA[
|
||||
.deps
|
||||
*.lo
|
||||
*.la
|
||||
]]>
|
||||
</programlisting>
|
||||
</informalexample>
|
||||
|
||||
<para>
|
||||
These lines tell <command>CVS</command> to ignore interim files generated
|
||||
by the PHP buildsystem. This is only a convenience, and can be omitted
|
||||
completely without ill effect.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The <filename>CREDITS</filename> file lists the contributors and/or
|
||||
maintainers of the extension in plain text format, preferably including
|
||||
contact information, and sometimes a website for the extension. This file
|
||||
is only one way to document this information. In a &link.pecl; package,
|
||||
this information is already maintained in <filename>package.xml</filename>,
|
||||
for example. This is another file which can be omitted without ill effect.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The <filename>package.xml</filename> file is specific to &link.pecl;-based
|
||||
extensions; it is a metainformation file which gives details about an
|
||||
extension's dependencies, authors, installation requirements, and other
|
||||
tidbits. In an extension not being hosted in &link.pecl;, this file is
|
||||
extraneous.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
</sect1>
|
||||
|
||||
<!-- Keep this comment at the end of the file
|
||||
Local variables:
|
||||
mode: sgml
|
||||
sgml-omittag:t
|
||||
sgml-shorttag:t
|
||||
sgml-minimize-attributes:nil
|
||||
sgml-always-quote-attributes:t
|
||||
sgml-indent-step:1
|
||||
sgml-indent-data:t
|
||||
indent-tabs-mode:nil
|
||||
sgml-parent-document:nil
|
||||
sgml-default-dtd-file:"../../../manual.ced"
|
||||
sgml-exposed-tags:nil
|
||||
sgml-local-catalogs:nil
|
||||
sgml-local-ecat-files:nil
|
||||
End:
|
||||
vim600: syn=xml fen fdm=syntax fdl=2 si
|
||||
vim: et tw=78 syn=sgml
|
||||
vi: ts=1 sw=1
|
||||
-->
|
||||
27
internals2/structure/globals.xml
Normal file
27
internals2/structure/globals.xml
Normal file
|
|
@ -0,0 +1,27 @@
|
|||
<?xml version="1.0" encoding="ISO-8859-1" ?>
|
||||
<!-- $Revision: 1.1 $ -->
|
||||
<sect1 xml:id="internals2.structure.globals" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
<title>Extension globals</title>
|
||||
<para/>
|
||||
</sect1>
|
||||
|
||||
<!-- Keep this comment at the end of the file
|
||||
Local variables:
|
||||
mode: sgml
|
||||
sgml-omittag:t
|
||||
sgml-shorttag:t
|
||||
sgml-minimize-attributes:nil
|
||||
sgml-always-quote-attributes:t
|
||||
sgml-indent-step:1
|
||||
sgml-indent-data:t
|
||||
indent-tabs-mode:nil
|
||||
sgml-parent-document:nil
|
||||
sgml-default-dtd-file:"../../../manual.ced"
|
||||
sgml-exposed-tags:nil
|
||||
sgml-local-catalogs:nil
|
||||
sgml-local-ecat-files:nil
|
||||
End:
|
||||
vim600: syn=xml fen fdm=syntax fdl=2 si
|
||||
vim: et tw=78 syn=sgml
|
||||
vi: ts=1 sw=1
|
||||
-->
|
||||
|
|
@ -1,9 +1,24 @@
|
|||
<?xml version="1.0" encoding="ISO-8859-1" ?>
|
||||
<!-- $Revision: 1.2 $ -->
|
||||
<chapter xml:id="internals2.structure" xmlns="http://docbook.org/ns/docbook">
|
||||
<!-- $Revision: 1.3 $ -->
|
||||
<chapter xml:id="internals2.structure" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
|
||||
<title>Extension structure</title>
|
||||
<para>
|
||||
Many extension-writing guides focus on simple examples first and ignore the
|
||||
requirements of more complex implementations until later. Often such guides
|
||||
must repeat themselves over and over in order to describe these new
|
||||
features. This section describes extension structure from the perspective of
|
||||
a mature, practical implementation, in order to prepare users for needs and
|
||||
issues they will almost always encounter in the process of extension
|
||||
development.
|
||||
</para>
|
||||
|
||||
&internals2.structure.files;
|
||||
&internals2.structure.modstruct;
|
||||
&internals2.structure.globals;
|
||||
&internals2.structure.lifecycle;
|
||||
&internals2.structure.tests;
|
||||
|
||||
</chapter>
|
||||
|
||||
<!-- Keep this comment at the end of the file
|
||||
|
|
|
|||
27
internals2/structure/lifecycle.xml
Normal file
27
internals2/structure/lifecycle.xml
Normal file
|
|
@ -0,0 +1,27 @@
|
|||
<?xml version="1.0" encoding="ISO-8859-1" ?>
|
||||
<!-- $Revision: 1.1 $ -->
|
||||
<sect1 xml:id="internals2.structure.lifecycle" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
<title>Life cycle of an extension</title>
|
||||
<para/>
|
||||
</sect1>
|
||||
|
||||
<!-- Keep this comment at the end of the file
|
||||
Local variables:
|
||||
mode: sgml
|
||||
sgml-omittag:t
|
||||
sgml-shorttag:t
|
||||
sgml-minimize-attributes:nil
|
||||
sgml-always-quote-attributes:t
|
||||
sgml-indent-step:1
|
||||
sgml-indent-data:t
|
||||
indent-tabs-mode:nil
|
||||
sgml-parent-document:nil
|
||||
sgml-default-dtd-file:"../../../manual.ced"
|
||||
sgml-exposed-tags:nil
|
||||
sgml-local-catalogs:nil
|
||||
sgml-local-ecat-files:nil
|
||||
End:
|
||||
vim600: syn=xml fen fdm=syntax fdl=2 si
|
||||
vim: et tw=78 syn=sgml
|
||||
vi: ts=1 sw=1
|
||||
-->
|
||||
27
internals2/structure/modstruct.xml
Normal file
27
internals2/structure/modstruct.xml
Normal file
|
|
@ -0,0 +1,27 @@
|
|||
<?xml version="1.0" encoding="ISO-8859-1" ?>
|
||||
<!-- $Revision: 1.1 $ -->
|
||||
<sect1 xml:id="internals2.structure.modstruct" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
<title>The zend_module structure</title>
|
||||
<para/>
|
||||
</sect1>
|
||||
|
||||
<!-- Keep this comment at the end of the file
|
||||
Local variables:
|
||||
mode: sgml
|
||||
sgml-omittag:t
|
||||
sgml-shorttag:t
|
||||
sgml-minimize-attributes:nil
|
||||
sgml-always-quote-attributes:t
|
||||
sgml-indent-step:1
|
||||
sgml-indent-data:t
|
||||
indent-tabs-mode:nil
|
||||
sgml-parent-document:nil
|
||||
sgml-default-dtd-file:"../../../manual.ced"
|
||||
sgml-exposed-tags:nil
|
||||
sgml-local-catalogs:nil
|
||||
sgml-local-ecat-files:nil
|
||||
End:
|
||||
vim600: syn=xml fen fdm=syntax fdl=2 si
|
||||
vim: et tw=78 syn=sgml
|
||||
vi: ts=1 sw=1
|
||||
-->
|
||||
27
internals2/structure/tests.xml
Normal file
27
internals2/structure/tests.xml
Normal file
|
|
@ -0,0 +1,27 @@
|
|||
<?xml version="1.0" encoding="ISO-8859-1" ?>
|
||||
<!-- $Revision: 1.1 $ -->
|
||||
<sect1 xml:id="internals2.structure.tests" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
<title>Testing an extension</title>
|
||||
<para/>
|
||||
</sect1>
|
||||
|
||||
<!-- Keep this comment at the end of the file
|
||||
Local variables:
|
||||
mode: sgml
|
||||
sgml-omittag:t
|
||||
sgml-shorttag:t
|
||||
sgml-minimize-attributes:nil
|
||||
sgml-always-quote-attributes:t
|
||||
sgml-indent-step:1
|
||||
sgml-indent-data:t
|
||||
indent-tabs-mode:nil
|
||||
sgml-parent-document:nil
|
||||
sgml-default-dtd-file:"../../../manual.ced"
|
||||
sgml-exposed-tags:nil
|
||||
sgml-local-catalogs:nil
|
||||
sgml-local-ecat-files:nil
|
||||
End:
|
||||
vim600: syn=xml fen fdm=syntax fdl=2 si
|
||||
vim: et tw=78 syn=sgml
|
||||
vi: ts=1 sw=1
|
||||
-->
|
||||
Loading…
Reference in a new issue