From 7a20c6dc511c39df0355f32ebeb89e16e8677834 Mon Sep 17 00:00:00 2001 From: Karen Arutyunov Date: Fri, 26 May 2023 22:08:52 +0300 Subject: Document package-description* and changes-type manifest values and adapt testscript to new values --- bpkg/rep-fetch.cxx | 117 ++++++++++++++++++++++++++------------------ doc/manual.cli | 49 ++++++++++++------- tests/pkg-verify.testscript | 1 + 3 files changed, 102 insertions(+), 65 deletions(-) diff --git a/bpkg/rep-fetch.cxx b/bpkg/rep-fetch.cxx index 17536da..6f31478 100644 --- a/bpkg/rep-fetch.cxx +++ b/bpkg/rep-fetch.cxx @@ -481,25 +481,35 @@ namespace bpkg // Load *-file values. // - m.load_files ( - [ev, &rd, &rl, &pl] - (const string& n, const path& p) -> optional - { - // Always expand the build-file values. - // - if (ev || n == "build-file") + try + { + m.load_files ( + [ev, &rd, &rl, &pl] + (const string& n, const path& p) -> optional { - return read_package_file (p, - n, - pl, - rd, - rl, - empty_string /* fragment */); - } - else - return nullopt; - }, - iu); + // Always expand the build-file values. + // + if (ev || n == "build-file") + { + return read_package_file (p, + n, + pl, + rd, + rl, + empty_string /* fragment */); + } + else + return nullopt; + }, + iu); + } + catch (const manifest_parsing& e) + { + diag_record dr (fail); + dr << e << info; + print_package_info (dr, pl, rl, nullopt /* fragment */); + dr << endf; + } // Load the bootstrap, root, and config/*.build buildfiles into the // respective *-build values, if requested and if they are not already @@ -679,38 +689,49 @@ namespace bpkg // Load *-file values. // - m.load_files ( - [ev, &td, &rl, &pl, &fr, &checkout_submodules] - (const string& n, const path& p) -> optional - { - // Always expand the build-file values. - // - if (ev || n == "build-file") + try + { + m.load_files ( + [ev, &td, &rl, &pl, &fr, &checkout_submodules] + (const string& n, const path& p) -> optional { - // Check out submodules if the referenced file doesn't exist. - // - // Note that this doesn't work for symlinks on Windows where - // git normally creates filesystem-agnostic symlinks that are - // indistinguishable from regular files (see fixup_worktree() - // for details). It seems like the only way to deal with that - // is to unconditionally checkout submodules on Windows. Let's - // not pessimize things for now (if someone really wants this - // to work, they can always enable real symlinks in git). + // Always expand the build-file values. // - if (!exists (td / pl / p)) - checkout_submodules (); - - return read_package_file (p, - n, - pl, - td, - rl, - fr.friendly_name); - } - else - return nullopt; - }, - iu); + if (ev || n == "build-file") + { + // Check out submodules if the referenced file doesn't exist. + // + // Note that this doesn't work for symlinks on Windows where + // git normally creates filesystem-agnostic symlinks that + // are indistinguishable from regular files (see + // fixup_worktree() for details). It seems like the only way + // to deal with that is to unconditionally checkout + // submodules on Windows. Let's not pessimize things for now + // (if someone really wants this to work, they can always + // enable real symlinks in git). + // + if (!exists (td / pl / p)) + checkout_submodules (); + + return read_package_file (p, + n, + pl, + td, + rl, + fr.friendly_name); + } + else + return nullopt; + }, + iu); + } + catch (const manifest_parsing& e) + { + diag_record dr (fail); + dr << e << info; + print_package_info (dr, pl, rl, fr.friendly_name); + dr << endf; + } // Load the bootstrap, root, and config/*.build buildfiles into the // respective *-build values, if requested and if they are not diff --git a/doc/manual.cli b/doc/manual.cli index e2ff1f0..8d9a1d2 100644 --- a/doc/manual.cli +++ b/doc/manual.cli @@ -1055,8 +1055,12 @@ license: [; ] [description]: [description-file]: [; ] [description-type]: +[package-description]: +[package-description-file]: [; ] +[package-description-type]: [changes]: [changes-file]: [; ] +[changes-type]: [url]: [; ] [doc-url]: [; ] @@ -1131,7 +1135,7 @@ and use the \c{upstream-version} value to preserve the original version for information. -\h2#manifest-package-type-language|\c{type, language}| +\h2#manifest-package-type-language|\c{type}, \c{language}| \ [type]: @@ -1385,23 +1389,30 @@ as well as words from its summary are already considered to be keywords and need not be repeated in this value. -\h2#manifest-package-description|\c{description}| +\h2#manifest-package-description|\c{description}, \c{package-description}| \ [description]: [description-file]: [; ] [description-type]: +[package-description]: +[package-description-file]: [; ] +[package-description-type]: \ -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 (for example, -\c{README}), but not both. +The detailed description of the project (\c{description}) and package +(\c{package-description}). If the package description is not specified, it is +assumed to be the same as the project description. It only makes sense to +specify the \c{package-description} value if the project and package are +maintained separately. A description can be provided either inline as a text +fragment or by referring to a file within a package (for example, \c{README}), +but not both. For \c{package-description-file} the recommended file name is +\c{PACKAGE-README} or \c{README-PACKAGE}. In the web interface (\c{brep}) the description is displayed according to its type. Currently, pre-formatted plain text, \l{https://github.github.com/gfm GitHub-Flavored Markdown}, and \l{https://spec.commonmark.org/current -CommonMark} are supported with the following \c{description-type} values, -respectively: +CommonMark} are supported with the following \c{*-type} values, respectively: \ text/plain @@ -1412,13 +1423,13 @@ text/markdown;variant=CommonMark If just \c{text/markdown} is specified, then the GitHub-Flavored Markdown (which is a superset of CommonMark) is assumed. -If the description type is not explicitly specified and the description is -specified as \c{description-file}, then an attempt to derive the type from the -file extension is made. Specifically, the \cb{.md} and \cb{.markdown} -extensions are mapped to \c{text/markdown}, the \cb{.txt} and no extension are -mapped to \c{text/plain}, and all other extensions are treated as an unknown -type, similar to unknown \c{description-type} values. And if the description -is not specified as a file, \c{text/plain} is assumed. +If a description type is not explicitly specified and the description is +specified as \c{*-file}, then an attempt to derive the type from the file +extension is made. Specifically, the \cb{.md} and \cb{.markdown} extensions +are mapped to \c{text/markdown}, the \cb{.txt} and no extension are mapped to +\c{text/plain}, and all other extensions are treated as an unknown type, +similar to unknown \c{*-type} values. And if a description is not specified as +a file, \c{text/plain} is assumed. \h2#manifest-package-changes|\c{changes}| @@ -1426,6 +1437,7 @@ is not specified as a file, \c{text/plain} is assumed. \ [changes]: [changes-file]: [; ] +[changes-type]: \ The description of changes in the release. @@ -1459,8 +1471,11 @@ changes: changes-file: NEWS \ -In the web interface (\c{brep}) the changes are displayed as pre-formatted -plain text, similar to the package description. +In the web interface (\c{brep}) the changes are displayed according to their +type, similar to the package description (see the +\l{#manifest-package-description \c{description}} value for details). If +the changes type is not explicitly specified, then the types deduced for +individual \c{changes} values must all be the same. \h2#manifest-package-url|\c{url}| @@ -2120,7 +2135,7 @@ dependencies by other packages and therefore should be built in a host configuration. See the \l{bbot \c{bbot} documentation} for details. -\h2#manifest-package-tests-examples-benchmarks|\c{tests, examples, benchmarks}| +\h2#manifest-package-tests-examples-benchmarks|\c{tests}, \c{examples}, \c{benchmarks}| \ [tests]: [*] [] diff --git a/tests/pkg-verify.testscript b/tests/pkg-verify.testscript index 69c29b0..7e7b5f3 100644 --- a/tests/pkg-verify.testscript +++ b/tests/pkg-verify.testscript @@ -88,6 +88,7 @@ $* --deep --ignore-unknown --manifest $src/foo-2.tar.gz >>EOO * First public release. \ + changes-type: text/plain url: http://www.example.org/foo email: foo-users@example.org depends: bar == 2 -- cgit v1.1