diff options
| -rw-r--r-- | bpkg/rep-add.cli | 22 | ||||
| -rwxr-xr-x | doc/cli.sh | 7 | ||||
| -rw-r--r-- | doc/manual.cli | 88 |
3 files changed, 77 insertions, 40 deletions
diff --git a/bpkg/rep-add.cli b/bpkg/rep-add.cli index 3925074..ff202a5 100644 --- a/bpkg/rep-add.cli +++ b/bpkg/rep-add.cli @@ -38,7 +38,8 @@ namespace bpkg A bpkg repository is \i{archive}-based. That is, it contains a collection of various packages/versions as archive files. For more information on - the structure of bpkg repositories refer to the \cb{bpkg} manual. + the structure of bpkg repositories refer to the \l{bpkg \cb{bpkg} + manual}. A git repository is \i{version control}-based. That is, it normally contains multiple versions of the same package (but can also contain @@ -85,17 +86,14 @@ namespace bpkg contains \cb{manifest}, then it is assumed to be a single-package repository with the \cb{manifest} file being its package manifest. Otherwise the \cb{packages} file should list the available packages as - directory paths relative to the repository root (which in turn should - contain the \cb{manifest} files). The \cb{packages} file is a manifest - (see the \cb{bpkg} manual for details on the manifest file format) that - should contain one or more \cb{location} values in the POSIX path - representation. For example: - - \ - : 1 - location: src/libfoo/ - location: src/foo/ - \ + described in \l{bpkg#manifest-package-list-git Package List Manifest for + \c{git} Repositories}. + + A git repository may also contain the \cb{repositories} file in the root + directory of the repository. This file can be used to describe the + repository itself as well as specify its prerequisite and complement + repositories. See \l{bpkg#manifest-repository-list Repository List + Manifest} for details on the format and semantics of this file. Supported git protocols are \cb{git://}, \cb{http://}, and \cb{https://} for remote repositories and \cb{file://} for local repositories. While @@ -38,12 +38,14 @@ function compile () cli -I .. -v project="bpkg" -v version="$version" -v date="$date" \ --include-base-last "${o[@]}" --generate-html --html-prologue-file \ -man-prologue.xhtml --html-epilogue-file man-epilogue.xhtml --html-suffix \ -.xhtml ../bpkg/$n.cli +man-prologue.xhtml --html-epilogue-file man-epilogue.xhtml --html-suffix .xhtml \ +--link-regex '%bpkg(#.+)?%build2-package-manager-manual.xhtml$1%' \ +../bpkg/$n.cli cli -I .. -v project="bpkg" -v version="$version" -v date="$date" \ --include-base-last "${o[@]}" --generate-man --man-prologue-file \ man-prologue.1 --man-epilogue-file man-epilogue.1 --man-suffix .1 \ +--link-regex '%bpkg(#.+)?%$1%' \ ../bpkg/$n.cli } @@ -72,6 +74,7 @@ cli -I .. \ --html-prologue-file doc-prologue.xhtml \ --html-epilogue-file doc-epilogue.xhtml \ --link-regex '%b([-.].+)%../../build2/doc/b$1%' \ +--link-regex '%build2(#.+)?%../../build2/doc/build2-build-system-manual.xhtml$1%' \ --output-prefix build2-package-manager- manual.cli html2ps -f doc.html2ps:a4.html2ps -o build2-package-manager-manual-a4.ps build2-package-manager-manual.xhtml diff --git a/doc/manual.cli b/doc/manual.cli index 6e57b7d..02287bd 100644 --- a/doc/manual.cli +++ b/doc/manual.cli @@ -28,8 +28,7 @@ Note also that if you are strating a new project that will use the \c{build2} toolchain, then it is strongly recommended that you use the \i{standard versioning} scheme which is a more strictly defined subset of semanic versioning and that allows automation of many version management tasks. See -\l{https://build2.org/build2/doc/build2-build-system-manual.xhtml#module-version -Version Module} for details. +\l{build2#module-version Version Module} for details. The \c{bpkg} package version has the following form: @@ -857,12 +856,12 @@ 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| +\h#manifest-package-list-bpkg|Package List Manifest for \c{bpkg} Repositories| -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: +The package list manifest (the \c{packages} file found in the \c{bpkg} +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> @@ -880,7 +879,7 @@ sha256sum: <sum> The detailed description of each value follows in the subsequent sections. -\h2#manifest-package-list-sha256sum|\c{sha256sum} (list manifest)| +\h2#manifest-package-list-bpkg-sha256sum|\c{sha256sum} (list manifest)| \ sha256sum: <sum> @@ -896,7 +895,7 @@ 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)| +\h2#manifest-package-list-bpkg-package-location|\c{location} (package manifest)| \ location: <path> @@ -910,7 +909,7 @@ 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)| +\h2#manifest-package-list-bpkg-package-sha256sum|\c{sha256sum} (package manifest)| \ sha256sum: <sum> @@ -920,12 +919,47 @@ 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-package-list-git|Package List Manifest for \c{git} Repositories| + +The package list manifest (the \c{packages} file found in the \c{git} +repository root directory) describes the list of packages available in the +repository. It is a (potentially empty) sequence of manifests with the +following synopsis: + +\ +location: <path> +\ + +The detailed description of each value follows in the subsequent sections. + +As an example, if our repository contained the \c{src/} subdirectory that in +turn contained the \c{libfoo} and \c{foo} packages, then the corresponding +\c{packages} file could look like this: + +\ +: 1 +location: src/libfoo/ +: +location: src/foo/ +\ + +\h2#manifest-package-list-git-location|\c{location}| + +\ +location: <path> +\ + +The path to the package directory relative to the repository root. It should +be in the POSIX representation. + + \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. +described below) describes a \c{bpkg} or \c{git} repository. The manifest +synopsis is presented next followed by the detailed description of each value +in subsequent sections. \ [location]: <uri> @@ -1089,7 +1123,8 @@ description. \ The X.509 certificate for the repository. It should be in the PEM format and -can only be specified for the base repository. +can only be specified for the base repository. Currently only used for the +\c{bpkg} repository type. 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 @@ -1100,7 +1135,7 @@ repository name(s) that are authenticated with this certificate. See 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. +See \l{#manifest-signature-bpkg Signature Manifest} for details. \h#manifest-repository-list|Repository List Manifest| @@ -1149,23 +1184,24 @@ https://pkg.example.org/1/math/stable \ -\h#manifest-signature|Signature Manifest| +\h#manifest-signature-bpkg|Signature Manifest for \c{bpkg} Repositories| -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. +The signature manifest (the \c{signature} file found in the \c{bpkg} +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}| +\h2#manifest-signature-bpkg-sha256sum|\c{sha256sum}| \ sha256sum: <sum> @@ -1176,7 +1212,7 @@ 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}| +\h2#manifest-signature-bpkg-signature|\c{signature}| \ signature: <sig> |