diff options
Diffstat (limited to 'doc/manual.cli')
| -rw-r--r-- | doc/manual.cli | 1019 |
1 files changed, 1019 insertions, 0 deletions
diff --git a/doc/manual.cli b/doc/manual.cli index b52cb52..cd94396 100644 --- a/doc/manual.cli +++ b/doc/manual.cli @@ -159,4 +159,1023 @@ multiple revisions of the same upstream version in the same respository. As a result, in the package object model, we have a version key as just {\i{epoch}, \i{upstream}, \i{prerel}} but also store the package revision so that it can be shown it to the user, etc.] + +\h1#manifests|Manifests| + +This chapter describes the general manifest file format as well as the +concrete manifests used by \c{bpkg}. + +Currently, three manifests are defined: package manifest, repository manifest, +and signature manifest. The former two manifests can also be combined into a +list of manifests to form the list of available packages and the description +of a repository, respectively. + +\h#manifest-format|Manifest Format| + +The manifest file is a UTF-8 encoded text file containing a list of name-value +pairs in the form: + +\ +<name>: <value> +\ + +For example: + +\ +name: libfoo +version: 1.2.3 +\ + +The name can contain any characters except \c{':'} and whitespaces. Newline +terminates the pair unless escaped with \c{'\'} (see below). Leading and +trailing whitespaces before and after name and value are ignored except in the +multi-line mode (see below). + +If, the first non-whitespace character on the line is \c{'#'}, then the rest +of the line is treated as a comment and ignored except if the preceding +newline was escaped or in the multi-line mode (see below). For example: + +\ +# This is a comment. +short: This is #not a comment +long: Also \ +#not a comment +\ + +The first name-value pair in the manifest file should always have an empty +name. The value of this special pair is the manifest format version. The +version value shall use the default (that is, non-multi-line) mode and shall +not use any escape sequences. Currently it should be \c{1}, for example: + +\ +: 1 +name: libfoo +version: 1.2.3 +\ + +Any new name that is added without incrementing the version must be optional +so that it can be safely ignored by older implementations. + +The special empty name pair can also be used to separate multiple +manifests. In this case the version may be omitted in the subsequent +manifests, for example: + +\ +: 1 +name: libfoo +version: 1.2.3 +: +name: libbar +version: 2.3.4 +\ + +To disable treating of a newline as a name-value pair terminator we can escape +it with \c{'\'}. Note that \c{'\'} is only treated as an escape sequence when +followed by a newline and both are simply removed from the stream (as opposed +to being replaced which a space). To enter a literal \c{'\'} at the end of the +value, use the \c{'\\'} sequence. For example: + +\ +description: Long text that doesn't fit into one line \ +so it is continued on the next line. +\ + +\ +windows-path: C:\foo\bar\\ +\ + +Notice that in the final example only the last \c{'\'} needs special handling +since it is the only one that is followed by a newline. + +One may notice that in this newline escaping scheme a line consisting of just +\c{'\'} followed by a newline has no use, except, perhaps, for visual +presentation of, arguably, dubious value. For example, this representation: + +\ +description: First line. \ +\\ +Second line. +\ + +Is semantically equivalent to: + +\ +description: First line. Second line. +\ + +As a result, such a sequence is \"overloaded\" to provide more useful +functionality in two ways: Firstly, if \c{':'} after the name is immediately +followed (ignoring whitespaces) by \c{'\'} and a newline, then it signals the +start of the multi-line mode. In this mode all subsequent newlines and \c{'#'} +are treated as ordinary characters rather than value terminators or comments +until a line consisting of just '\' and a newline (the multi-line mode +terminator). For example: + +\ +description:\ +First paragraph. +# +Second paragraph. +\\ +\ + +Expressed as a C-string, the value in the above example is: + +\ +\"First paragraph.\n#\nSecond paragraph.\" +\ + + +[Note: if we didn't expect to ever need to specify a name with an empty value, +then an empty value could have turned on the multi-line mode, for example: + +\ +description: +First paragraph. +# +Second paragraph. +\\ +\ + +There are two reasons we don't do this: we don't want to close the door on +empty values and we want a more explicit \"introductor\" for the multi-line +mode since it is quite different compared to the simple mode.] + +Note that in the multi-line mode we can still use newline escaping to split +long lines, for example: + +\ +description:\ +First paragraph that doesn't fit into one line \ +so it is continued on the next line. +Second paragraph. +\\ +\ + +In the simple (that is, non-multi-line) mode, the sole \c{'\'} and newline +sequence is overloaded to mean a newline. So the previous example can also be +represented like this: + +\ +description: First paragraph that doesn't fit into one \ +line so it is continued on the next line.\ +\\ +Second paragraph. +\ + +Note that the multi-line mode can be used to capture a value with leading +and/or trailing whitespaces, for example: + +\ +description:\ + test + +\\ +\ + +The C-string representing this value is: + +\ +\" test\n\" +\ + +EOF can be used instead of a newline to terminate both simple and multi-line +values. For example the following representation results in the same value as +in the previous example. + +\ +description:\ + test + +<EOF> +\ + +By convention, names are all in lower case and multi-word names are separated +with \c{'-'}. Note that names are case-sensitive. + +Also by convention, the following name suffixes are used to denote common +types of values: + +\ +-file +-url +-email +\ + +For example: + +\ +description: Inline description +description-file: README +package-url: http://www.example.com +package-email: john@example.com +\ + +Other common name suffixes (such as -feed) could be added later. + +[Note: generally, unless there is a good reason not to, we keep values +lower-case (for example, \c{requires} values such as \c{c++11} or +\c{linux}). An example where we use upper/mixed case would be \c{license}; it +seems unlikely \c{gplv2} would be better than \c{GPLv2}.] + +A number of name-value pairs described below allow for the value proper to be +optionally followed by ';' and a comment. Such comments serve as additional +documentation for the user and should be full sentence(s), that is start with +a capital letter and end with a period. Note that unlike \c{#}-style comments +which are ignored, these comments are considered to be part of the value. For +example: + +\ +email: foo-users@example.com; Public mailing list. +\ + +It is recommended that you keep comments short, single-sentence. Note that +non-comment semicolons in such values have to be escape with a backslash, for +example: + +\ +url: http://git.example.com/?p=foo\;a=tree +\ + +In the manifest specifications described below optional components are +enclosed in square brackets (\c{[]}). If the name is enclosed in \c{[]} then +the name-value pair is optional, otherwise \- required. For example: + +\ +name: <name> +license: <licenses> [; <comment>] +[description]: <text> +\ + +In the above example \c{name} is required, \c{license} has an optional +component (comment), and \c{description} is optional. + + +\h#manifest-package|Package Manifest| + +The package manifest (the \c{manifest} file found in the package's root +directory) describes a \c{bpkg} package. The manifest synopsis is presented +next followed by the detailed description of each value in subsequent +sections. + +\ +name: <name> +version: <version> +[priority]: <priority> [; <comment>] +summary: <text> +license: <licenses> [; <comment>] +[tags]: <tags> +[description]: <text> +[description-file]: <path> [; <comment>] +[changes]: <text> +[changes-file]: <path> [; <comment>] + +url: <url> [; <comment>] +[doc-url]: <url> [; <comment>] +[src-url]: <url> [; <comment>] +[package-url]: <url> [; <comment>] + +email: <email> [; <comment>] +[package-email]: <email> [; <comment>] +[build-email]: <email> [; <comment>] + +[depends]: [?][*] <alternatives> [; <comment>] +[requires]: [?] [<alternatives>] [; <comment>] + +[build-include]: <config>[/<target>] [; <comment>] +[build-exclude]: <config>[/<target>] [; <comment>] +\ + +\h2#manifest-package-name|\c{name}| + +\ +name: <name> +\ + +The package name. Note that the package name comparison is case-insensitive +but the case is preserved for display, in file names, etc. [Note: the reason +for not using case-sensitive comparison is Windows file names.] + +Package naming guidelines: + +\ol| + + \li|Use lower-case letters.| + + \li|Use \c{'-'} to separate words, for example, \c{foo-bar}.| + + \li|Use \c{lib} prefix for libraries, for example, \c{libfoo-bar}.|| + + +\h2#manifest-package-version|\c{version}| + +\ +version: <version> +\ + +The package version. See \l{#package-version Package Version} for the version +format description. Note that the version case is preserved for display, in +file names, etc. + +\h2#manifest-package-|\c{priority}| + +\ +[priority]: <priority> [; <comment>] + +<priority> = security | high | medium | low +\ + +The release priority (optional). As a guideline, use \c{security} for security +fixes, \c{high} for critical bug fixes, \c{medium} for important bug fixes, +and \c{low} for minor fixes and/or feature releases. If not specified, \c{low} +is assumed. + + +\h2#manifest-package-summary|\c{summary}| + +\ +summary: <text> +\ + +The short description of the package. + + +\h2#manifest-package-license|\c{license}| + +\ +license: <licenses> [; <comment>] + +<licenses> = <license> [, <license>]* +\ + +The package lincense. The format is a comma-separated list of license names +under which this package is distributed. This list has the \i{AND} semantics, +that is, the user must comply with all the licenses listed. To capture +alternative licensing options use multiple \c{license} values, for example: + +\ +license: LGPLv2, MIT +license: BSD +\ + +In the above example, the package can be used either under the BSD license or +both LGPLv2 and MIT. + +For complex licensing schemes it is recommended to add comments as an aid to +the user, for example: + +\ +license: LGPLv2, MIT; If linking with GNU TLS. +license: BSD; If linking with OpenSSL. +\ + +To assist automated processing, the following pre-defined values should be +used for the common licenses: + +\ +MIT +GPLv2 +GPLv3 +LGPLv2 +LGPLv3 +ASLv1 ; Apache License 1.0. +ASLv1.1 ; Apache License 1.1. +ASLv2 ; Apache License 2.0. +BSD ; BSD 3-clause. +BSD-Original ; BSD original. + +public domain +available source ; Not free software/open source. +proprietary +\ + +[Note: an example of automated processing could be filtering for non-copyleft +licensed packages.] + +\h2#manifest-package-tags|\c{tags}| + +\ +[tags]: <tags> + +<tags> = <tag> [, <tag>]* +\ + +The package tags (optional). The format is a comma-separated list of words +that describe this package. + +[Note: originally, support for multi-word tags were considered, however this +quickly degenerated into quite a complex functionality. In particular, in such +a case we should probably treat multi-word tags as if the single word as well +as shorter, multi-word derivations were also mentioned. That is, \"xml pull +parser\" should be equivalent to \"xml pull parser, xml pull, xml parser, +pull parser, xml, pull, parser\". + +On the user side, if exact phrase matches are favored, then this serves as an +encouragement to come up with ever more elaborate multi-word tags to \"cover\" +as much ground as possible. For example, \"streaming c++ xml pull parser\". + +As a result, we will start simple and only allow single-word tags.] + + +\h2#manifest-package-description|\c{description}| + +\ +[description]: <text> +[description-file]: <path> [; <comment>] +\ + +The detailed description of the package. It can be provided either inline as a +text fragment or by referring to a file within a package (e.g., \c{README}), +but not both. + +In the web interface (\c{brep}) the description is formatted into one or more +paragraphs using blank lines as paragraph separators. Specifically, it is not +represented as \c{<pre>} so any kind of additional plain text formatting (for +example, lists) will be lost and should not be used in the description. + + +\h2#manifest-package-changes|\c{changes}| + +\ +[changes]: <text> +[changes-file]: <path> [; <comment>] +\ + +The description of changes in the release. + +[Note: the tricky aspect is what happens if the upstream release stays the +same (and has, say, a \c{NEWS} file to which we point) but we need to make +another package release, for example, to apply a critical patch.] + +Multiple \c{changes} values can be present which are all concatenated in the +order specified, that is, the first value is considered to be the most recent +[Note: similar to \c{ChangeLog} and \c{NEWS} files]. For example: + +\ +changes: 1.2.3-2: applied upstream patch for critical bug bar +changes: 1.2.3-1: applied upstream patch for critical bug foo +changes-file: NEWS +\ + +Or: + +\ +changes:\ +1.2.3-2 + - applied upstream patch for critical bug bar + - regenerated documentation + +1.2.3-1 + - applied upstream patch for critical bug foo +\\ +changes-file: NEWS +\ + +In the web interface (\c{brep}) the changes are displayed as pre-formatted +plain text. [Note: we could use the comment to \"hint\" at the file format.] + + +\h2#manifest-package-url|\c{url}| + +\ +url: <url> [; <comment>] +\ + +The project home page URL. + + +\h2#manifest-package-doc-url|\c{doc-url}| + +\ +[doc-url]: <url> [; <comment>] +\ + +The project documentation URL. + + +\h2#manifest-package-src-url|\c{src-url}| + +\ +[src-url]: <url> [; <comment>] +\ + +The project source repository URL. + + +\h2#manifest-package-package-url|\c{package-url}| + +\ +[package-url]: <url> [; <comment>] +\ + +The package home page URL. If not specified, then assumed to be the same as +\c{url}. It only makes sense to specify this value if the project and +packaged are maintained separately. + + +\h2#manifest-package-email|\c{email}| + +\ +email: <email> [; <comment>] +\ + +The project email address. For example, a support mailing list. + + +\h2#manifest-package-package-email|\c{package-email}| + +\ +[package-email]: <email> [; <comment>] +\ + +The package email address. If not specified, then assumed to be the same as +\c{email}. It only makes sense to specify this value if the project and +packaged are maintained separately. + + +\h2#manifest-package-build-email|\c{build-email}| + +\ +[build-email]: <email> [; <comment>] +\ + +The build notification email address. It is used to send build result +notifications by automated build bots. If not specified, then assumed to be +the same as \c{package-email}. If specified but empty, then no build result +notifications for this package are sent by email. + +\h2#manifest-package-depends|\c{depends}| + +\ +[depends]: [?][*] <alternatives> [; <comment>] + +<alternatives> := <dependency> [ '|' <dependency>]* +<dependency> := <name> [<constraint>] +<constraint> := <comparison> | <range> +<comparison> := ('==' | '>' | '<' | '>=' | '<=') <version> +<range> := ('(' | '[') <version> <version> (')' | ']') +\ + +The prerequisite packages. If the \c{depends} value start with \c{'*'}, then +it is a \i{build-time} prerequisite. Otherwise it is \i{run-time}. [Note: most +of the build-time prerequisites are expected to be tools such as code +generator, so you can think of \c{'*'} as the executable mark printed by +\c{ls}. An important difference between the two kind of dependencies is that +in case of cross-compilation a build-time dependency must be built for the +build machine, not the target.] + +Two special build-time dependency names are recognized and checked in an ad +hoc manner: \c{build2} (the \c{build2} build system) and \c{bpkg} (the +\c{build2} package manager). This allows us to specify the required build +system and package manager versions, for example: + +\ +depends: * build2 >= 0.6.0 +depends: * bpkg >= 0.6.0 +\ + +Each \c{depends} value can specify multiple packages with the \i{OR} +semantics. While multiple \c{depends} values are used to specify multiple +packages with the \i{AND} semantics. A value that starts with \c{'?'} is a +conditional prerequisite. Whether such a prerequisite will be in effect can +only be determined at the package configuration time. It is recommended that +you provide a comment for each conditional prerequisite as an aid to the user. +For example: + +\ +depends: libz +depends: libfoo [1.2.0 1.3.0-); Need libfoo 1.2.X. +depends: libgnutls >= 1.2.3 | libopenssl >= 2.3.4 +depends: ? libboost-regex >= 1.52.0; Only if no C++11 <regex>. +depends: ? libqtcore >= 5.0.0; Only if GUI is enabled. +\ + +It is recommended that you specify unconditional dependencies first with +simple (no alternatives) dependencies leading each set. + +Note that internally comparisons can be represented as ranges (that is, \c{[v, +v]} for \c{==}, \c{(v, inf)} for \c{>}, etc). However, for display and +serialization such representations should be converted back to simple +comparisons. While it is possible that the original manifest specified +equality as \c{[v, v]}, it is acceptable to display/serialize it as +simpler \c{==}. + +\h2#manifest-package-requires|\c{requires}| + +\ +[requires]: [?] [<alternatives>] [; <comment>] + +<alternatives> := <requirement> [ '|' <requirement>]* +<requirement> := <id> | <dependency> +\ + +The package requirements (other than other packages). Such requirements are +normally checked during package configuration by the build system and the only +purpose of capturing them in the manifest is for documentation. Similar to +\c{depends}, a value that starts with \c{'?'} is a conditional +requirement. For example: + +\ +requires: linux | windows | macosx +requires: c++11 +requires: ? ; VC 15 or later if targeting Windows. +requires: ? ; libc++ if using Clang on Mac OS. +\ + +Note that \c{requires} should also be used to specify dependencies on external +libraries, that is, then ones not packaged or not in the repository. In this +case it may make sense to also specify the version constraint. For example: + +\ +requires: zlib >= 1.2.0; Most systems already have it or get from zlib.net. +\ + +It is recommended that you specify unconditional requirements first with +simple (no alternatives) requirements leading each set. + +To assist automated processing, the following pre-defined ids should be used +for the common requirements: + +\ +c++98 +c++03 +c++11 +c++14 +c++17 +c++21 +\ + +\ +posix +linux +macos +freebsd +windows +\ + +\ +gcc[_X.Y.Z] ; For example: gcc_6, gcc_4.9, gcc_5.0.0 +clang[_X.Y] ; For example: clang_6, clang_3.4, clang_3.4.1 +msvc[_NU] ; For example: msvc_14, msvc_15u3 +\ + +\h2#manifest-package-include-exclude|\c{build-{include,exclude\}}| + +\ +[build-include]: <config>[/<target>] [; <comment>] +[build-exclude]: <config>[/<target>] [; <comment>] +\ + +The package build inclusions and exclusions. The \c{build-include} and +\c{build-exclude} values specify the build configurations and, optionally, +targets the package should or should not be built for by automated build +bots. The \i{config} and \i{target} values are filesystem wildcard patterns +which are matched against the build configuration names and target names (see +the \c{bbot} documentation for details). + +The exclusion and inclusion patterns are applied in the order specified with +the first match determining whether the package will be built for this +configuration and target. If none of the patterns match (or none we +specified), then the package is built. + +As an example, the following value will exclude 32-bit builds for the VC14 +compiler: + +\ +build-exclude: *-msvc_14*/i?86-* ; Linker crash. +\ + +As another example, the following pair of values will make sure that a package +is only built on Linux: + +\ +build-include: linux* +build-exclude: * ; Only supported on Linux. +\ + +Note that the comment of the matching exclusion is used by the web interface +(\c{brep}) to display the reason for the build exclusion. + + +\h#manifest-package-list|Package List Manifest| + +The package list manifest (the \c{packages} file found in the repository root +directory) describes the list of packages available in the repository. First +comes a manifest that describes the list itself (referred to as the list +manifest). The list manifest synopsis is presented next: + +\ +sha256sum: <sum> +\ + +After the list manifest comes a (potentially empty) sequence of package +manifests. These manifests shall not contain any \c{*-file} values (such +values should be converted to their inline versions) but must contain the +following additional (to package manifest) values: + +\ +location: <path> +sha256sum: <sum> +\ + +The detailed description of each value follows in the subsequent sections. + +\h2#manifest-package-list-sha256sum|\c{sha256sum} (list manifest)| + +\ +sha256sum: <sum> +\ + +The SHA256 checksum of the \c{repositories} file (described below) that +corresponds to this repository. The \i{sum} value should be 64 characters long +(that is, just the SHA256 value, no file name or any other markers), be +calculated in the binary mode, and use lower-case letters. + +[Note: this checksum is used to make sure that the \c{repositories} file that +was fetched is the same as the one that was used to create the \c{packages} +file. This also means that if \c{repositories} is modified in any way, then +\c{packages} must be regenerated as well.] + +\h2#manifest-package-list-package-location|\c{location} (package manifest)| + +\ +location: <path> +\ + +The path to the package archive file relative to the repository root. It +should be in the POSIX representation. + +[Note: if the repository keeps multiple versions of the package and places +them all into the repository root directory, it can get untidy. With +\c{location} we allow for sub-directories.] + + +\h2#manifest-package-list-package-sha256sum|\c{sha256sum} (package manifest)| + +\ +sha256sum: <sum> +\ + +The SHA256 checksum of the package archive file. The \i{sum} value should be +64 characters long (that is, just the SHA256 value, no file name or any other +markers), be calculated in the binary mode, and use lower-case letters. + +\h#manifest-repository|Repository Manifest| + +The repository manifest (only used as part of the repository manifest list +described below) describes a \c{bpkg} repository. The manifest synopsis is +presented next followed by the detailed description of each value in +subsequent sections. + +\ +[location]: <uri> +[role]: base|prerequisite|complement +[url]: <url> +[email]: <email> [; <comment>] +[summary]: <text> +[description]: <text> +[certificate]: <pem> +\ + +See also the Repository Chaining documentation for further information @@ TODO. + +\h2#manifest-repository-location|\c{location}| + +\ +[location]: <uri> +\ + +The location of the repository root. It can be an HTTP(S) URL or a filesystem +path. The location can only and must be omitted for the base repository. If +the path is relative, then it is treated as relative to the base repository +location. + +While POSIX systems normally only support POSIX paths (that is, forward +slashes only), Windows is generally able to handle both slash types. As a +result, it is recommended that POSIX paths are always used in the \c{location} +values, except, perhaps, if the repository is explicitly Windows-only by, for +example, having a location that is an absolute Windows path with the drive +letter. [Note: the bpkg package manager will always try to represent the +location as a POSIX path and only fallback to the native representation if +that is not possible (for example, there is a drive letter in the path).] + + +\h2#manifest-repository-role|\c{role}| + +\ +[role]: base|prerequisite|complement +\ + +The repository role. If the \c{location} value is omitted, then the role can +be omitted or it must be \c{base}. If the \c{location} value is present, then +the role can be omitted (in which case it is assume to be \c{prerequisite}) or +it must be either \c{prerequisite} or \c{complement}. + + +\h2#manifest-repository-url|\c{url}| + +\ +[url]: <url> +\ + +The repository's web interface (\c{brep}) URL. It can only be specified for +the base repository (the web interface URLs for prerequisite/complement +repositories can be extracted from their respective manifests). + +For example, given the following \c{url} value: + +\ +url: https://example.org/hello/ +\ + +The package details page for \c{libfoo} located in this repository will be +\c{https://example.org/hello/libfoo}. + +The web interface URL can also be specified as relative to the repository +location (the \c{location} value). In this case \i{url} should start with two +path components each being either \c{.} or \c{..}. If the first component is +\c{..}, then the \c{www}, \c{pkg} or \c{bpkg} domain component, if any, is +removed from the \c{location} URL host, just like when deriving the repository +name. + +Similarly, if the second component is \c{..}, then the \c{pkg} or \c{bpkg} +path component, if any, is removed from the \c{location} URL path, again, just +like when deriving the repository name. + +Finally, the version component is removed from the \c{location} URL path, the +rest (after the two \c{.}/\c{..} components) of the \c{url} value is appended +to it, and the resulting path is normalized with all remaining \c{..} and +\c{.} applied normally. + +For examples, assuming repository location is: + +\ +https://pkg.example.org/test/pkg/1/hello/stable +\ + +The following listing shows some of the possible combinations (the \c{<>} +marker is used to highlight the changes): + +\ +./. -> https://pkg.example.org/test/pkg/hello/stable +../. -> https://< >example.org/test/pkg/hello/stable +./.. -> https://pkg.example.org/test/< >hello/stable +../.. -> https://< >example.org/test/< >hello/stable +././.. -> https://pkg.example.org/test/pkg/hello< > +../../../.. -> https://< >example.org/test< > +\ + +[Note: the rationale for the relative web interface URLs is to allow +deployment of the same repository to slightly different configuration, for +example, during development, testing, and public use. For instance, for +development we may use the \c{https://example.org/pkg/} setup while in +production it becomes \c{https://pkg.example.org/}. By specifying the web +interface location as, say, \c{../.}, we can run the web interface at +these respective locations using a single repository manifest.] + + +\h2#manifest-repository-email|\c{email}| + +\ +[email]: <email> [; <comment>] +\ + +The repository email address. It must and can only be specified for the base +repository. The email address is displayed by the web interface (\c{brep}) in +the repository about page and could be used to contact the maintainers about +issues with the repository. + + +\h2#manifest-repository-summary|\c{summary}| + +\ +[summary]: <text> +\ + +The short description of the repository. It must and can only be specified for +the base repository. + + +\h2#manifest-repository-description|\c{description}| + +\ +[description]: <text> +\ + +The detailed description of the repository. It can only be specified for the +base repository. + +In the web interface (\c{brep}) the description is formatted into one or more +paragraphs using blank lines as paragraph separators, similar to the package +description. + + +\h2#manifest-repository-certificate|\c{certificate}| + +\ +[certificate]: <pem> +\ + +The X.509 certificate for the repository. It should be in the PEM format and +can only be specified for the base repository. + +The certificate should contain the \c{CN} and \c{O} components in the subject +as well as the \c{email:} component in the subject alternative names. The +\c{CN} component should start with \c{name:} and continue with the repository +name prefix/wildcard (without trailing slash) that will be used to verify the +repository name(s) that are authenticated with this certificate. See +\l{bpkg-repository-signing(1)} for details. + +If this value is present then the \c{packages} file must be signed with the +corresponding private key and the signature saved in the \c{signature} file. +See \l{#manifest-signature Signature Manifest} for details. + + +\h#manifest-repository-list|Repository List Manifest| + +@@ TODO See the Repository Chaining document for more information on the +terminology and semantics. + +The repository list manifest (the \c{repositories} file found in the +repository root directory) describes the repository. First comes a +(potentially empty) sequence of repository manifests that describe the +prerequisite and complement repositories. After this sequence must come the +manifest for the base repository, that is, the repository that this manifest +list is describing. The location value in this last manifest must be +omitted. [Note: since we got hold of the manifest list, then we presumably +already know the location of the base repository.] + +As an example, a repository manifest list for the \c{math/testing} +repository could look like this: + +\ +# math/testing +# +: 1 +location: https://pkg.example.org/1/misc/testing +: +role: complement +location: ../stable +: +email: math-pkg@example.org +summary: Math package repository +\ + +Here the first manifest describes a prerequisite repository, the second +manifest \- a complement repository, and the third manifest \- the base +repository itself. Note that the complement repository's location is specified +as a relative path. For example, if the base repository location were: + +\ +https://pkg.example.org/1/math/testing +\ + +Then the completement's location would be: + +\ +https://pkg.example.org/1/math/stable +\ + + +\h#manifest-signature|Signature Manifest| + +The signature manifest (the \c{signature} file found in the repository root +directory) contains the signature of the repository's \c{packages} file. In +order to detect the situation where the downloaded \c{signature} and +\c{packages} files belong to different updates, the manifest contains both the +checksum and the signature (which is the encrypted checksum). [Note: we cannot +rely on just the signature since a mismatch could mean either a split update +or tampering.] The manifest synopsis is presented next followed by the +detailed description of each value in subsequent sections. + +\ +sha256sum: <sum> +signature: <sig> +\ + +\h2#manifest-signature-sha256sum|\c{sha256sum}| + +\ +sha256sum: <sum> +\ + +The SHA256 checksum of the \c{packages} file. The \i{sum} value should be 64 +characters long (that is, just the SHA256 value, no file name or any other +markers), be calculated in the binary mode, and use lower-case letters. + + +\h2#manifest-signature-signature|\c{signature}| + +\ +signature: <sig> +\ + +The signature of the \c{packages} file. It should be calculated by encrypting +the above \c{sha256sum} value with the repository certificate's private key +and then \c{base64}-encoding the result. " + +//@@ TODO items (grep). +//@@ TODO: repository chaining, fix link in #manifest-repostiory. +//@@ TODO: complete license list (MPL, ...) +//@@ Are there any restrictions on requires ids? Is this valid: msvc >= 15u3? |