diff options
Diffstat (limited to 'doc/packaging.cli')
| -rw-r--r-- | doc/packaging.cli | 68 |
1 files changed, 61 insertions, 7 deletions
diff --git a/doc/packaging.cli b/doc/packaging.cli index 07486a5..d861457 100644 --- a/doc/packaging.cli +++ b/doc/packaging.cli @@ -13,8 +13,6 @@ // TODO: // -// @@ Update pinned repositories (libevent, libasio, xxd, libzstd). -// // @@ Update build2-packaging front page with link to this guide (add // organization README?) // @@ -1112,7 +1110,7 @@ libfoo/ Once the overall layout looks right, the next step is to take a closer look at the generated \c{buildfiles} to make sure that overall they match the upstream build. Of particular interest are the header and source directory -\c{buildfiles} (\c{libfoo/include/foo/buildifle} and \c{libfoo/src/buildifle} +\c{buildfiles} (\c{libfoo/include/foo/buildfile} and \c{libfoo/src/buildfile} in the above listing) which define how the library is built and installed. Here we are focusing on the macro-level differences that are easier to change @@ -2166,7 +2164,7 @@ $ bdep sync -a --disfigure config.libfoo.debug=true For each library that your package depends on (and which you have added to \c{manifest} in the \l{#core-fill-depend Add dependencies} step), -you need to first determine whether it's an interface of implementation +you need to first determine whether it's an interface or implementation dependency and then import it either into the \c{intf_libs} or \c{impl_libs} variable, respectively. @@ -2515,7 +2513,7 @@ else {obja objs}{util}: cxx.poptions += -DFOO_POSIX \ -\N|Not that target-specific \c{*.poptions} and \c{*.coptions} must be +\N|Note that target-specific \c{*.poptions} and \c{*.coptions} must be specified on the object file targets while \c{*.loptions} and \c{*.libs} \- on the library or executable targets.| @@ -3078,6 +3076,7 @@ $ b test: tests/@/tmp/libfoo-tests-out/ \ \ > b install config.install.root=c:\tmp\install +> set \"PATH=c:\tmp\install\bin;%PATH%\" > b test: tests\@c:\tmp\libfoo-tests-out\^ config.cc.loptions=/LIBPATH:c:\tmp\install\lib \ @@ -5318,7 +5317,9 @@ libfoo ^1.2.3 \h1#faq|Packaging FAQ| -\h#faq-alpha-stable|Why is my package in \c{alpha} rather than \c{stable}?| +\h#faq-publish|Publishing FAQ| + +\h2#faq-publish-alpha|Why is my package in \c{alpha} rather than \c{stable}?| If your package uses a semver version (or semver-like, that is, has three version components) and the first component is zero (for example, \c{0.1.0}), @@ -5340,7 +5341,7 @@ first component upstream does not imply alpha quality. Getting an explicit statement to this effect from upstream is recommended. -\h#faq-publish-stage|Where to publish if package requires staged toolchain?| +\h2#faq-publish-stage|Where to publish if package requires staged toolchain?| If your package requires the \l{https://build2.org/community.xhtml#stage staged toolchain}, for example, because it needs a feature or bugfix that is not yet @@ -5388,5 +5389,58 @@ $ bdep publish --repository=https://stage.build2.org ... || +\h2#faq-publish-owner|Why \"project owner authentication failed\" while publishing?| + +If you are getting the following error while attempting to publish a new +version of a package: + +\ +$ bdep publish +... +error: project owner authentication failed +\ + +Then this means the remote \c{git} repository you are using does not match the +one from which you (or someone else) has published the initial version of the +package. + +In \c{build2} we use the ownership of the package \c{git} repository as a +proxy for the ownership of the package name on \l{https://cppget.org +cppget.org}. Specifically, when you publish the package for the first time, +we record the \c{git} URL for its package repository. And any further versions +of this package can only be submitted by someone who has write access to this +repository. See \l{bdep-publish(1)} for details. + +Based on this background, the first step you need to take when getting the +above owner authentication error is to understand its cause. For that, first +use the \c{git-config} command to see the URL you are using locally: + +\ +$ git config --get remote.origin.url +\ + +Then look in the \l{https://github.com/cppget/ \c{git} repositories} that back +\l{https://cppget.org cppget.org} and \l{https://queue.cppget.org +queue.cppget.org} and find the URL that is recorded in the \c{owners/} +subdirectory in the corresponding \c{package-owner.manifest} file. + +Note that your local URL will normally be SSH while the recorded URL will +always be HTTPS. Provided that the host names match, the part to look in for +differences is the path component. One common cause of a mismatch is the +missing \c{.git} extension. For example (local first, recorded second): + +\ +git@github.com:build2-packaging/zstd +https://github.com/build2-packaging/zstd.git +\ + +In this case adding the missing extension to the local URL should fix the +error. + +If, however, the discrepancy is expected, for example, because you have +renamed the package repository or moved it to a new location, the ownership +information will need to be updated manually. In this case feel free to submit +a pull request with the necessary changes or +\l{https://build2.org/community.xhtml#help get in touch}. " |