aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--bpkg/rep-add.cli22
-rwxr-xr-xdoc/cli.sh7
-rw-r--r--doc/manual.cli88
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
diff --git a/doc/cli.sh b/doc/cli.sh
index a925838..661d65c 100755
--- a/doc/cli.sh
+++ b/doc/cli.sh
@@ -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>