From cb44dbe27f3366f7c019d2f2e26b8e9579fa265f Mon Sep 17 00:00:00 2001 From: P. J. McDermott Date: Mon, 13 Aug 2012 22:19:11 -0400 Subject: Finish moving SPF 2.0 into a book. Omitted (at least temporarily) are "Packaging Recommendations" and "Example Files". --- (limited to 'specs/spf-2.0/overview.mdwn') diff --git a/specs/spf-2.0/overview.mdwn b/specs/spf-2.0/overview.mdwn new file mode 100644 index 0000000..b4e6f09 --- /dev/null +++ b/specs/spf-2.0/overview.mdwn @@ -0,0 +1,246 @@ +Directory Tree [tree] +===================== + +The source package directory hierarchy can be summarized with the following +tree: + + / + | No naming requirements are made for this directory. + +- .pkg/ + | | Required for each binary package after execution of "config". + | +- control + | | Required. + | | Metadata about the binary package. + | +- install + | | Required. + | | A list of patterns to match files to be installed in the binary + | | package. + | +- platconf + | | Optional. + | | A list of run-time configuration files. + | +- postinst + | | Optional. + | | A maintainer script to be executed after a binary package is + | | unpacked. + | +- postrm + | | Optional. + | | A maintainer script to be executed after a binary package is + | | removed. + | +- preinst + | | Optional. + | | A maintainer script to be executed before a binary package is + | | unpacked. + | \- prerm + | Optional. + | A maintainer script to be executed before a binary package is + | removed. + +- build + | Required after execution of "config". + | A makefile with target rules to build the binary package(s). + +- changelog + | Required. + | A log of changes made to the source package. + +- config + | Optional. + | A shell script to configure the package build. + +- control + | Required. + | Metadata about the source package. + +- copyright + | Required. + | Information about copyrights and licenses in the source package. + +- format + | Required. + | A magic file to identify the source format version. Should simply + | contain the string "2.0". + +- patches/ + | Optional. + | Patches to be applied to package sources before building. + +- -.tar. + | Optional. + | Upstream source archive (for non-native packages). + +- platconf + | Optional. + | A list of build-time configuration files. + \- src/ + Optional. + Package sources (for native packages). + + +Descriptions of Files [files] +============================= + +All of the following files are located under what is called a "source package +directory" (`` in the tree in $[sectlink][tree]). No +naming requirements are made for this directory. + +`.pkg/` [files-binpkg.pkg] +---------------------------------- + +After execution of the `config` file, for each binary package there must exist a +directory named `.pkg`, where `` is the name of the binary +package. + +Binary package names may only consist of lowercase Latin letters, digits, plus +and minus signs, and periods. Names must be at least two characters long and +must start with either a letter or a digit. (A regular expression for this is +`[a-z0-9][a-z0-9+.-]+`.) + +This directory contains metadata and scripts for a binary package. + +`.pkg/control` [files-binpkg.pkg-control] +------------------------------------------------- + +This file is required. + +This file contains control fields describing the binary package. See +$[sectlink][control] for the syntax of this file and $[sectlink][fields-bin] for +the list of control fields in this file. + +`.pkg/install` [files-binpkg.pkg-install] +------------------------------------------------- + +This file is required. + +This file contains a list of patterns to match files to be installed in the +binary package. + +Each line in this file is a pattern that is expanded to match files as explained +in [POSIX.1-2008, Shell & Utilities Volume, Section 2.6.6][posix-xcu-2.6.6]. + +A file or directory in the destination directory may not be matched by more than +one binary package's `install` file. The behavior of package building tools in +such a case is undefined. + +`.pkg/platconf` [files-binpkg.pkg-platconf] +--------------------------------------------------- + +This file is optional. Its presence indicates that a binary package is +platform-specific. + +This file contains a list of run-time configuration files to be installed in the +binary package. Files listed in this file shall not be listed in the binary +package's `install` file. + +See $[sectlink][platconf] for the syntax of this file. + +`.pkg/postinst` [files-binpkg.pkg-postinst] +--------------------------------------------------- + +This file is optional. + +This file is a maintainer script to be executed after a binary package is +unpacked. See $[sectlink][scripts] for more information about maintainer +scripts. + +`.pkg/postrm` [files-binpkg.pkg-postrm] +----------------------------------------------- + +This file is optional. + +This file is a maintainer script to be executed after a binary package is +removed. See $[sectlink][scripts] for more information about maintainer +scripts. + +`.pkg/preinst` [files-binpkg.pkg-preinst] +------------------------------------------------- + +This file is optional. + +This file is a maintainer script to be executed before a binary package is +unpacked. See $[sectlink][scripts] for more information about maintainer +scripts. + +`.pkg/prerm` [files-binpkg.pkg-prerm] +--------------------------------------------- + +This file is optional. + +This file is a maintainer script to be executed before a binary package is +removed. See $[sectlink][scripts] for more information about maintainer +scripts. + +`build` [files-build] +--------------------- + +After execution of the `config` file, this file must exist. + +This file is a makefile that controls the building of binary packages. See +$[sectlink][build] for requirements for this file. + +`changelog` [files-changelog] +----------------------------- + +This file is required. + +This file is a log of changes made to the source package. See +$[sectlink][changelog] for the format of this file. + +`config` [files-config] +----------------------- + +This file is optional. + +This file is a script in shell command language that configures the package +build. See $[sectlink][config] for requirements for this file. + +`control` [files-control] +------------------------- + +This file is required. + +This file contains control fields describing the source package. See +$[sectlink][control] for the syntax of this file and $[sectlink][fields-src] for +the list of control fields in this file. + +`copyright` [files-copyright] +----------------------------- + +This file is required. + +This file contains information about the copyrights in and licenses for the +source package. This specification currently makes no requirements for the +format of this file. + +`format` [files-format] +----------------------- + +This file is required. + +This "magic" file identifies the format version of the source package. For +packages in this version of the source package format, this file should simply +contain the string `2.0`. + +`patches/` [files-patches] +-------------------------- + +This directory is optional. + +This directory shall contain patches to be applied to package sources before +configuring and building any binary packages. + +See $[sectlink][patches] for the syntax of patch files. + +`-.tar.` [files-src-src-ver-tar-ext] +---------------------------------------------------------- + +TODO + +`platconf` [files-platconf] +--------------------------- + +This file is optional. Its presence indicates that each binary package is +platform-specific. + +This file contains a list of build-time configuration files to be installed into +the package building work area. + +See $[sectlink][platconf] for the syntax of this file. + +`src/` [files-src] +------------------ + +TODO + + +[posix-xcu-2.6.6]: http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_06_06 -- cgit v0.9.1