1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
|
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 297078 $ -->
<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="&url.codegen;">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_counter.h</filename></term>
<listitem>
<para>
When building an extension as static module into the PHP binary the
build system expects a header file with <literal>php_</literal>
prepended to the extension name which includes a declaration for a
pointer to the extension's module structure. This file usually contains
additional macros, prototypes, and globals, just like any header.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>counter.c</filename></term>
<listitem>
<para>
Main extension source file. By convention, the name of this file
is the extension name, but 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 the counter extension might look like
this:
</para>
<example xml:id="internals2.structure.files.ex1">
<title>Files in the counter extension, in no particular order</title>
<screen>
<![CDATA[
ext/
counter/
.cvsignore
config.m4
config.w32
counter_util.h
counter_util.c
php_counter.h
counter.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. The main purpose of
this file is generating the credits information for bundled extensions as
used by <function>phpcredits</function>. By convention the first line of
the file should hold the name of the extension, the second a comma
separated list of contributors. The contributors are usually ordered by the
chronological order of their contributions. 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:"~/.phpdoc/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
-->
|
