diff options
Diffstat (limited to 'specs/spf-2.0')
-rw-r--r-- | specs/spf-2.0/buildsys.mdwn | 38 | ||||
-rw-r--r-- | specs/spf-2.0/fields.mdwn | 69 | ||||
-rw-r--r-- | specs/spf-2.0/index.mdwn | 21 | ||||
-rw-r--r-- | specs/spf-2.0/metadata.mdwn | 26 |
4 files changed, 134 insertions, 20 deletions
diff --git a/specs/spf-2.0/buildsys.mdwn b/specs/spf-2.0/buildsys.mdwn index 07c8039..a483d46 100644 --- a/specs/spf-2.0/buildsys.mdwn +++ b/specs/spf-2.0/buildsys.mdwn @@ -49,9 +49,21 @@ Certain environment variables (see $[sectlink][env-vars]) shall be set when the Build Work Area [work-area] =========================== -When building packages, a new directory named `tmp` shall be created in the -source package directory. In this directory, the package source code shall be -copied or unpacked into a directory called `src` shall be created. +When building packages, the package building tool shall create a new directory +named `tmp` in the source package directory. In this directory, the package +building tool shall copy or unpack the package source code into a directory +called `src`. + +For each binary package, the `build` file (see $[sectlink][build]) must create +within the work area `tmp` a directory named `<binpkg>.data`, where `<binpkg>` +is the name of the binary package. See $[sectlink][bin-name] for the +requirements on binary package names. + +Before installing binary package data files into `<binpkg>.data`, the `build` +file may stage them in a different directory immediately under the work area +directory `tmp`. For example, opkhelper's **oh-autoinstall**(1) installs files +into `tmp/dest/` before **oh-installfiles**(1) moves them to +`tmp/<binpkg>.data/`. After all expected binary packages have been built, the work area (`tmp` and its children) shall be removed. @@ -60,14 +72,9 @@ children) shall be removed. Environment Variables [env-vars] ================================ -Certain environment variables shall be set to provide to the configuration -script and build makefile information about the package and the environments in -and for which binary packages are to be built. - -The terms "build system" and "host system" below are used according to [the -convention set by GNU Autoconf][target-triplets]. The build system is the type -of system on which a package is built. The host system is the type of system on -which a binary package is expected to be natively installed and used. +The package building tool shall set certain environment variables to provide to +the build makefile information about the package and the environments in and for +which binary packages are to be built. Package Variables [env-vars-pkg] -------------------------------- @@ -100,9 +107,18 @@ The following environment variables shall be set to describe the source package: architecture-dependent or architecture-independent packages may have been selected for building. + * `OPK_WORK_AREA` + + The absolute path to the build work area (see $[sectlink][work-area]). + Build and Host System Variables [env-vars-sys] ---------------------------------------------- +The terms "build system" and "host system" are used according to [the convention +set by GNU Autoconf][target-triplets]. The build system is the type of system +on which a package is built. The host system is the type of system on which a +binary package is expected to be natively installed and used. + The following environment variables shall be set to describe the build system: * `OPK_BUILD_ARCH` diff --git a/specs/spf-2.0/fields.mdwn b/specs/spf-2.0/fields.mdwn index e50c2b4..c28db8d 100644 --- a/specs/spf-2.0/fields.mdwn +++ b/specs/spf-2.0/fields.mdwn @@ -12,6 +12,8 @@ The fields in the source package metadata are: A list of packages that must be installed before the package can be built. + See $[sectlink][rel-syntax] for the syntax of this field. + Variable substitutions are performed on the value of this field. * `Homepage` (optional) @@ -58,6 +60,53 @@ The fields in the binary package metadata are: least some of the provided files are only usable on systems of the named platform(s). + * `Section` (optional, may be required in a future version of this Source + Package Format) + + The name of the section in the package archive into which this package is to + be installed. Packages with a `Section` field must provide only files + related to the specified section. The value may be any one of the + following: + + - The string `boot` for packages containing only boot loaders, kernel + images, and device firmware; + - The string `dbg` for architecture-dependent packages containing only + debugging symbols; + - The string `dev` for platform-independent packages containing only + utilities used to build other packages, such as distribution package build + utilities, compilers, and utilities that configure compiler and linker + flags; + - The string `doc` for architecture-independent platform-independent + packages containing only manual pages and other upstream documentation + files; + - The string `lib` for architecture-dependent packages containing only + shared libraries and object files; + - The string `libdev` for architecture-dependent packages containing only + header files, unversioned library symbolic links used when linking, and + configuration files and architecture-independent utilities that configure + compiler and linker flags; + - The string `locale` for architecture-independent platform-independent + packages containing only locale files; + - The string `share` for architecture-independent packages containing only + data; and + - The string `util` for packages containing only executable files, such as + utilities and binaries run by other programs. + + No packages may declare any relationships (via `Depends`, `Recommends`, + etc.) with packages in sections `dbg`, `doc`, or `locale`. Only packages + in section `boot` may declare relationships on other packages in the same + section. Only binary packages in section `dev` and source packages (via + `Build-Depends`) may declare relationships with packages in sections `dev` + and `libdev`. These restrictions allow feed lists for sections `boot`, + `dbg`, `dev`, `doc`, `libdev`, and `locale` to be excluded from systems that + don't need the packages they contain. That is, only sections `lib`, + `share`, and `util` are available on all systems, and additionally sections + `dev` and `libdev` are available when building packages. + + All packages in section `lib` must allow coinstallation of packages of the + same name and different architectures. Specifically, all non-directory + files must have architecture-qualified paths. + * `Essential` (optional) A flag to indicate whether the package is essential for the functioning of a @@ -70,18 +119,26 @@ The fields in the binary package metadata are: A list of packages that must be installed and configured before the package may itself be configured. + See $[sectlink][rel-syntax] for the syntax of this field. + Variable substitutions are performed on the value of this field. * `Recommends` (optional) + See $[sectlink][rel-syntax] for the syntax of this field. + Variable substitutions are performed on the value of this field. * `Suggests` (optional) + See $[sectlink][rel-syntax] for the syntax of this field. + Variable substitutions are performed on the value of this field. * `Pre-Depends` (optional) + See $[sectlink][rel-syntax] for the syntax of this field. + A list of packages that must be installed before the package may itself be installed. @@ -89,14 +146,20 @@ The fields in the binary package metadata are: * `Conflicts` (optional) + See $[sectlink][rel-syntax] for the syntax of this field. + Variable substitutions are performed on the value of this field. * `Provides` (optional) + See $[sectlink][rel-syntax] for the syntax of this field. + Variable substitutions are performed on the value of this field. * `Replaces` (optional) + See $[sectlink][rel-syntax] for the syntax of this field. + Variable substitutions are performed on the value of this field. * `Description` (required) @@ -106,3 +169,9 @@ The fields in the binary package metadata are: description. Variable substitutions are performed on the value of this field. + + +Package Relationship Fields Syntax [rel-syntax] +=============================================== + +TODO diff --git a/specs/spf-2.0/index.mdwn b/specs/spf-2.0/index.mdwn index 021eded..2a45902 100644 --- a/specs/spf-2.0/index.mdwn +++ b/specs/spf-2.0/index.mdwn @@ -1,6 +1,6 @@ Status: DRAFT - Date: 2013-05-25 - Revises: Source Package Format 1.0 + Date: 2023-09-25 + Obsoletes: Source Package Format 1.0 Abstract @@ -15,11 +15,26 @@ Status This specification is in `DRAFT` status. It is a work-in-progress and is subject to change. Comments and revisions are welcome. +Although some sections have yet to be written, this specification is already +implemented by package building tools and over 100 source packages since 2012. +Any changes made to written sections will maintain compatibility with the +existing format and implementations. + +Occasionally, new optional elements of the format are added and existing +limitations are relaxed. Such changes are made in tandem with corresponding +support being added to package building tools. Source packages that make use of +such new elements and relaxed limitations are responsible for ensuring that +package building tools are new enough to support them, by listing such tools and +minimum required versions in the `Build-Depends` control field (see +$[sectlink][fields-src]). Refer to the release notes of package building tools +to identify the versions in which support is added for changes to this Source +Package Format. + Legal Notice ============ -Copyright © 2012 Patrick "P. J." McDermott +Copyright © 2012, 2019-2021, 2023 Patrick "P. J." McDermott Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/specs/spf-2.0/metadata.mdwn b/specs/spf-2.0/metadata.mdwn index dd0a749..913fd43 100644 --- a/specs/spf-2.0/metadata.mdwn +++ b/specs/spf-2.0/metadata.mdwn @@ -107,7 +107,9 @@ 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+.-]+`.) -Source package names may not begin with the reserved string "src-". +Source package names may not begin with the reserved string "src-". *This +limitation is expected to be removed in a future draft of this version of this +Source Package Format.* Binary Package Names [bin-name] ------------------------------- @@ -117,11 +119,14 @@ 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+.-]+`.) -Binary package names may not begin with the reserved string "src-". +Binary package names may not begin with the reserved string "src-". *This +limitation is expected to be removed in a future draft of this version of this +Source Package Format.* A binary package clean name is a binary package name with all plus and minus signs and periods removed. No two binary packages built from the same source -package may have the same clean name. +package may have the same clean name. *This limitation is expected to be +removed in a future draft of this version of this Source Package Format.* Source Package Version Identifier [src-ver] @@ -129,7 +134,14 @@ Source Package Version Identifier [src-ver] In general, the syntax of source package version identifiers is: - <pkgver>[+sip<siprev>][-<pkgrev>][+<dist>~<distrev>][~bpu<distnum>+<bpurev>] + [<epoch>:]<pkgver>[+sip<siprev>][-<pkgrev>][+<dist>~<distrev>][~bpu<distnum>+<bpurev>] + +`<epoch>` should almost always be omitted, in which case it is effectively zero. +It may be used when the upstream version numbering scheme changes or when one or +more binary packages are migrated to a different source package with a different +upstream version numbering scheme. It must be a string of one or more digits, +the first of which must be greater than or equal to `1`. (A regular expression +for this is `[1-9][0-9]*`.) `<pkgver>` is the version of the original upstream package or the native package. It may only consist of lowercase Latin letters, digits, periods, @@ -148,8 +160,10 @@ regular expression for this is `[1-9][0-9]*`.) should be omitted for native packages. It should be incremented on each revision of packaging while `<pkgver>` and `<siprev>` remain constant. It should be reset to `1` for the first revision of packaging for a new upstream -package version or source archive repack. It must be a string of one or more -digits. (A regular expression for this is `[0-9]+`.) +package version or source archive repack if the package is to be installed into +the `trunk` distribution; otherwise it should be set to `0` and never +incremented. It must be a string of one or more digits. (A regular expression +for this is `[0-9]+`.) If the package is to be installed into a distribution other than `trunk`, the string `+<dist>~<distrev>` must be included in the version identifier. `<dist>` |