From 062465f032fbbefd33a2f228e876ca791fafa83f Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Sat, 2 Sep 2017 11:17:02 +0200 Subject: Move manifest specification to manual --- doc/manual.cli | 1019 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1019 insertions(+) (limited to 'doc') 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: + +\ +: +\ + +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 + + +\ + +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: +license: [; ] +[description]: +\ + +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: +version: +[priority]: [; ] +summary: +license: [; ] +[tags]: +[description]: +[description-file]: [; ] +[changes]: +[changes-file]: [; ] + +url: [; ] +[doc-url]: [; ] +[src-url]: [; ] +[package-url]: [; ] + +email: [; ] +[package-email]: [; ] +[build-email]: [; ] + +[depends]: [?][*] [; ] +[requires]: [?] [] [; ] + +[build-include]: [/] [; ] +[build-exclude]: [/] [; ] +\ + +\h2#manifest-package-name|\c{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: +\ + +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]: [; ] + + = 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: +\ + +The short description of the package. + + +\h2#manifest-package-license|\c{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]: + + = [, ]* +\ + +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]: +[description-file]: [; ] +\ + +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{
} 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]: 
+[changes-file]:  [; ]
+\
+
+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:  [; ]
+\
+
+The project home page URL.
+
+
+\h2#manifest-package-doc-url|\c{doc-url}|
+
+\
+[doc-url]:  [; ]
+\
+
+The project documentation URL.
+
+
+\h2#manifest-package-src-url|\c{src-url}|
+
+\
+[src-url]:  [; ]
+\
+
+The project source repository URL.
+
+
+\h2#manifest-package-package-url|\c{package-url}|
+
+\
+[package-url]:  [; ]
+\
+
+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:  [; ]
+\
+
+The project email address. For example, a support mailing list.
+
+
+\h2#manifest-package-package-email|\c{package-email}|
+
+\
+[package-email]:  [; ]
+\
+
+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]:  [; ]
+\
+
+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]: [?][*]  [; ]
+
+ :=  [ '|' ]*
+   :=  []
+   :=  | 
+   := ('==' | '>' | '<' | '>=' | '<=') 
+        := ('(' | '[')   (')' | ']')
+\
+
+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 .
+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]: [?] [] [; ]
+
+ :=  [ '|' ]*
+  :=  | 
+\
+
+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]: [/] [; ]
+[build-exclude]: [/] [; ]
+\
+
+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: 
+\
+
+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: 
+sha256sum: 
+\
+
+The detailed description of each value follows in the subsequent sections.
+
+\h2#manifest-package-list-sha256sum|\c{sha256sum} (list manifest)|
+
+\
+sha256sum: 
+\
+
+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: 
+\
+
+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: 
+\
+
+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]: 
+[role]: base|prerequisite|complement
+[url]: 
+[email]:  [; ]
+[summary]: 
+[description]: 
+[certificate]: 
+\
+
+See also the Repository Chaining documentation for further information @@ TODO.
+
+\h2#manifest-repository-location|\c{location}|
+
+\
+[location]: 
+\
+
+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]: 
+\
+
+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]:  [; ]
+\
+
+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]: 
+\
+
+The short description of the repository. It must and can only be specified for
+the base repository.
+
+
+\h2#manifest-repository-description|\c{description}|
+
+\
+[description]: 
+\
+
+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]: 
+\
+
+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: 
+signature: 
+\
+
+\h2#manifest-signature-sha256sum|\c{sha256sum}|
+
+\
+sha256sum: 
+\
+
+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: 
+\
+
+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?
-- 
cgit v1.1