[Zope-CVS] CVS: Packages/zpkgtools/doc - metadata.txt:1.2
Fred L. Drake, Jr.
fred at zope.com
Mon Mar 15 17:28:49 EST 2004
Update of /cvs-repository/Packages/zpkgtools/doc
In directory cvs.zope.org:/tmp/cvs-serv23493
Modified Files:
metadata.txt
Log Message:
add documentation for the package.conf files
=== Packages/zpkgtools/doc/metadata.txt 1.1 => 1.2 ===
--- Packages/zpkgtools/doc/metadata.txt:1.1 Sat Mar 13 00:52:10 2004
+++ Packages/zpkgtools/doc/metadata.txt Mon Mar 15 17:28:48 2004
@@ -2,6 +2,9 @@
Metadata Descriptions for Distributions
=======================================
+Overview
+--------
+
Packages will be described using a collection of files that contain
different aspects of the package metadata.
@@ -34,8 +37,105 @@
file; this file has the same format as PKG-INFO.
package.conf
- This file contains information on building extension modules and, if
- needed, detailed information about the files to be included in the
- package for distribution. Information about scripts and
- documentation files will also be included in this file. The format
- of this file is not yet documented.
+ This file contains information on building extension modules.
+ Information about scripts and documentation files will also be
+ included in this file.
+
+
+Embedded Package Definitions
+----------------------------
+
+Packages can include a `package.conf` that contains information about
+special files in the package (such as documentation and scripts), and
+what extensions need to be built. This file is a ZConfig-like
+configuration file that can contain the following settings, repeated
+as necessary:
+
+**documentation**
+ The name of a file or directory containing documentation. This is
+ used to support RPM generation.
+
+**script**
+ Only files may be identified using this. These files are included
+ in the distribution and will be installed as executable scripts for
+ the end user.
+
+For paths, POSIX path separators must be used, and Unix-style glob
+expansion is performed. Path names may not include leading or
+trailing whitespace. Directories named `CVS`, `RCS`, `SCCS`, or
+`.svn` are ignored, as are files named `.cvsignore`.
+
+Paths can only refer to descendents of the directory containing
+`package.conf`, never to that directory itself or anything higher up
+the filesystem hierarchy.
+
+Support for Compiled Extensions
+-------------------------------
+
+Compiled extensions are described using **<extension>** sections in
+the `package.conf` file. The name of the section should be the name
+of the extension module within the package. For example, the
+extension ``persistent.cPersistence`` would be represented using a
+section of the form::
+
+ <extension cPersistence>
+ ...
+ </extension>
+
+The **<extension>** section can contain the settings described below.
+All of these can be repeated with the exception of the **language**
+setting.
+
+**define**
+ Define additional symbols for the C preprocessor. Values must be of
+ the form ``NAME`` or ``NAME=value``. For example::
+
+ define NAME
+
+ is equivalent to including the following line at the top of the C
+ source::
+
+ #define NAME
+
+ and this::
+
+ define NAME=value
+
+ is equivalent to this line in C::
+
+ #define NAME value
+
+ The ``NAME`` portion must be a valid C identifier.
+
+**depends-on**
+ Additional files that the compiled extension depends on. This is
+ used by distutils to determine whether the extension needs to be
+ recompiled. Since the source files are identified by the **source**
+ setting, this is normally only needed for header files.
+
+ XXX This is the one place I've seen a need to point outside the
+ current package. In ZODB, the BTrees extension modules need to pick
+ up `../persistent/cPersistence.h`.
+
+**language**
+ The source language of the extension; this may be needed to control
+ compiler selection if unusual extensions are used for the source
+ files. This is not normally needed.
+
+**source**
+ Source files for the extension. Each file is compiled into object
+ code, and the individual objects are linked to create the
+ extension module.
+
+**undefine**
+ Specify one or more macros that should not be initially defined by
+ preprocessor. For example, this line::
+
+ undefine NAME ANOTHER
+
+ is equivalent to the source lines::
+
+ #undef NAME
+ #undef ANOTHER
+
+ at the top of the compilation unit.
More information about the Zope-CVS
mailing list