diff options
Diffstat (limited to 'doc')
| -rwxr-xr-x | doc/cli.sh | 2 | ||||
| -rw-r--r-- | doc/intro.cli | 55 | ||||
| -rw-r--r-- | doc/packaging-review-checklist.md | 80 | ||||
| -rw-r--r-- | doc/packaging.cli | 83 |
4 files changed, 174 insertions, 46 deletions
@@ -1,6 +1,6 @@ #! /usr/bin/env bash -version=0.17.0-a.0.z +version=0.18.0-a.0.z trap 'exit 1' ERR set -o errtrace # Trap in functions. diff --git a/doc/intro.cli b/doc/intro.cli index 6671cbd..6ec3d04 100644 --- a/doc/intro.cli +++ b/doc/intro.cli @@ -2436,40 +2436,14 @@ along these lines: \ /usr/local/ ├── bin/ -│ └── hello -├── include/ -│ ├── libformat/ -│ │ ├── export.hxx -│ │ ├── format.hxx -│ │ └── version.hxx -│ ├── libhello/ -│ │ ├── export.hxx -│ │ ├── hello.hxx -│ │ └── version.hxx -│ └── libprint/ -│ ├── export.hxx -│ ├── print.hxx -│ └── version.hxx +│ └── hello ├── lib/ -│ ├── libformat-1.0.so -│ ├── libformat.so -> libformat-1.0.so -│ ├── libhello-1.1.so -│ ├── libhello.so -> libhello-1.1.so -│ ├── libprint-1.0.so -│ ├── libprint.so -> libprint-1.0.so -│ └── pkgconfig/ -│ ├── libformat.pc -│ ├── libhello.pc -│ └── libprint.pc +│ ├── libformat-1.0.so +│ ├── libhello-1.1.so +│ └── libprint-1.0.so └── share/ └── doc/ - ├── libformat/ - │ ├── manifest - │ └── README.md - ├── libhello/ - │ ├── manifest - │ └── README.md - └── libprint/ + └── hello/ ├── manifest └── README.md \ @@ -2503,6 +2477,25 @@ uninstall libformat-1.0.0/libformat/libs{format} <- /usr/local/lib/ ... \ +\N|From the above listing we can gather that only the shared library binaries +were installed. In particular, neither static library binaries nor headers and +other development-related files (such as non-versioned shared library +symlinks, \c{pkg-config} \c{.pc} files, etc) were installed. + +The reason for this behavior is that by default the \l{bpkg-pkg-install(1)} +command only instructs the build system to install packages that were +specified on the command line (\c{hello} in out case) while the build system +in turn installs from dependency packages only what's necessary for the +packages it was instructed to install. In our case, installing the \c{hello} +also requires installing the shared library binaries that it uses but none of +the development-related files (we don't need library headers in order to run +an executable). + +However, this default behavior of \l{bpkg-pkg-install(1)} (and +\l{bpkg-pkg-uninstall(1)}) can be changed with the \c{--recursive} option, +which instructs \c{bpkg} to additionally fully install/uninstall dependency +packages.| + Rather than installing the package locally we could instead generate a \i{binary distribution package} for it using the \l{bpkg-pkg-bindist(1)} command. Such a binary package can then be installed on a different diff --git a/doc/packaging-review-checklist.md b/doc/packaging-review-checklist.md new file mode 100644 index 0000000..367212f --- /dev/null +++ b/doc/packaging-review-checklist.md @@ -0,0 +1,80 @@ +**NOTE**: the items in this checklist should only be checked off by the person doing the review. The author of the package may indicate the completion of any outstanding items in comments. + +- [ ] Repository in the [build2-packaging organization][build2-packaging] if third-party package. +- [ ] Repository/project/package names consistent with upstream, [Debian][debian-pkgs] (see [repository name][rep-name], [package name][pkg-name]). +- [ ] If library without `lib` prefix, no clashes with executable named (see [package name][pkg-name]). +- [ ] Uses git submodule and symlinks for upstream, submodule at correct release commit (see [upstream submodule][upstream-submodule], [upstream symlinks][upstream-symlink]). +- [ ] Follows upstream layout (within reason) (see [package layout][upstream-layout]). +- [ ] [Does not bundle dependencies][dont-bundle-deps]. + +- [ ] Successful builds on [queue.cppget.org][queue]. +- [ ] Package archive sizes are not excessive and don't contain unnecessary files. + +- [ ] `manifest`: `name`/`project`/`version` values make sense. +- [ ] `manifest`: [`summary`][manifest-summary] value follows guidelines. +- [ ] `manifest`: [`license`][manifest-license] value is SPDX, matches upstream license(s). +- [ ] `manifest`: [`depends`][manifest-depends] values make sense, have corresponding [buildfile imports][manifest-depends-import]. + +- [ ] `build/bootstrap.build`: makes sense (project name, modules; see [project-wide build system files][build-wide]). +- [ ] `build/root.build`: makes sense (`cxx.std=latest`). +- [ ] `build/export.build`: makes sense. + +- [ ] Header/Source `buildfile`: [bdep-new generated][use-bdep-new]. +- [ ] Header `buildfile`: [overall makes sense][hdr-build]. +- [ ] Header `buildfile`: headers installed into library subdirectory or include library name ([background][bad-header-inclusion]). +- [ ] Source `buildfile`: [overall makes sense][src-build]. +- [ ] Source `buildfile`: [library is not header-only if upstream supports compiled][header-only]. +- [ ] Source `buildfile`: [doesn't use or export undesirable options][compile-options]. + +- [ ] Root `buildfile`: [overall makes sense][root-build]. +- [ ] Root `buildfile`: includes upstream `LICENSE` file (or equivalent). +- [ ] Root `buildfile`: [doesn't build main targets][root-main-targets]. + +- [ ] Doesn't violate any other [What Not to Do][not-to-do] points without good reason. + +- [ ] Above `buildfile` checks applied to tests/examples/etc subprojects/packages. +- [ ] If smoke test, [makes sense][test-smoke] (includes public header, calls non-inline function). + +- [ ] `PACKAGE-README.md`: [makes sense][pkg-readme]. + +- [ ] Above checks applied to all packages. + +- [ ] Repository `README.md`: [makes sense][rep-readme]. + +- [ ] Release is tagged and pushed to `git` repository. + +[build2-packaging]: https://github.com/build2-packaging/ +[upstream-layout]: https://build2.org/stage/build2-toolchain/doc/build2-toolchain-packaging.xhtml#dont-change-upstream +[debian-pkgs]: https://packages.debian.org/ +[rep-name]: https://build2.org/stage/build2-toolchain/doc/build2-toolchain-packaging.xhtml#core-repo-name +[pkg-name]: https://build2.org/stage/build2-toolchain/doc/build2-toolchain-packaging.xhtml#core-package-name +[upstream-submodule]: https://build2.org/stage/build2-toolchain/doc/build2-toolchain-packaging.xhtml#core-repo-submodule +[upstream-symlink]: https://build2.org/stage/build2-toolchain/doc/build2-toolchain-packaging.xhtml#core-fill-source +[upstream-layout]: https://build2.org/stage/build2-toolchain/doc/build2-toolchain-packaging.xhtml#dont-change-upstream +[dont-bundle-deps]: https://build2.org/stage/build2-toolchain/doc/build2-toolchain-packaging.xhtml#dont-bundle + +[queue]: https://queue.cppget.org + +[not-to-do]: https://build2.org/stage/build2-toolchain/doc/build2-toolchain-packaging.xhtml#dont-do + +[manifest-license]: https://build2.org/stage/build2-toolchain/doc/build2-toolchain-packaging.xhtml#core-root-manifest-license +[manifest-summary]: https://build2.org/stage/build2-toolchain/doc/build2-toolchain-packaging.xhtml#core-root-manifest-summary +[manifest-depends]: https://build2.org/stage/build2-toolchain/doc/build2-toolchain-packaging.xhtml#core-fill-depend +[manifest-depends-import]: https://build2.org/stage/build2-toolchain/doc/build2-toolchain-packaging.xhtml#core-adjust-build-src-source-dep + +[build-wide]: https://build2.org/stage/build2-toolchain/doc/build2-toolchain-packaging.xhtml#core-adjust-build-wide + +[use-bdep-new]: https://build2.org/stage/build2-toolchain/doc/build2-toolchain-packaging.xhtml#dont-from-scratch +[compile-options]: https://github.com/build2/HOWTO/blob/master/entries/compile-options-in-buildfile.md +[header-only]: https://build2.org/stage/build2-toolchain/doc/build2-toolchain-packaging.xhtml#dont-header-only +[bad-header-inclusion]: https://build2.org/stage/build2-toolchain/doc/build2-toolchain-packaging.xhtml#howto-bad-inclusion-practice +[hdr-build]: https://build2.org/stage/build2-toolchain/doc/build2-toolchain-packaging.xhtml#core-adjust-build-src-header +[src-build]: https://build2.org/stage/build2-toolchain/doc/build2-toolchain-packaging.xhtml#core-adjust-build-src-source + +[root-build]: https://build2.org/stage/build2-toolchain/doc/build2-toolchain-packaging.xhtml#core-root-buildfile +[root-main-targets]: https://build2.org/stage/build2-toolchain/doc/build2-toolchain-packaging.xhtml#dont-main-target-root-buildfile + +[test-smoke]: https://build2.org/stage/build2-toolchain/doc/build2-toolchain-packaging.xhtml#core-test-smoke-adjust + +[pkg-readme]: https://build2.org/stage/build2-toolchain/doc/build2-toolchain-packaging.xhtml#core-root-package-readme +[rep-readme]: https://build2.org/stage/build2-toolchain/doc/build2-toolchain-packaging.xhtml#core-repo-readme diff --git a/doc/packaging.cli b/doc/packaging.cli index 07486a5..a88f7cb 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?) // @@ -528,7 +526,7 @@ name differs from upstream, then there is likely a good reason for that and it is worth trying to understand what it is. \N|Tip: when trying to find the corresponding Debian package, search for the -executable file name in the package contents if you cannot fine the package by +executable file name in the package contents if you cannot find the package by its upstream name. Also consider searching in the \c{unstable} distribution in addition to \c{stable} for newer packages.| @@ -637,7 +635,7 @@ however, that we often deviate from Debian's splits, especially when it comes to libraries. Such differences are usually due to Debian focusing on binary packages while in \c{build2} we are focusing on source packages. -To give a few example, \c{libevent} shown in the above table provides several +To give a few examples, \c{libevent} shown in the above table provides several libraries (\c{libevent-core}, \c{libevent-extra}, etc) and in Debian it is actually split into several binary packages along these lines. In \c{build2}, however, there is a single source package that provides all these libraries @@ -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 @@ -1162,7 +1160,7 @@ $ b clean \N|One relatively common case where the installation location may not match upstream are libraries that include their headers without the subdirectory prefix (for example, \c{<foo_util.h>} instead of \c{<foo/util.h>}). In such -cases, in the \c{bdep-new} command, you want to use \i{prefix} rather that +cases, in the \c{bdep-new} command, you may want to use \i{prefix} rather than \i{source subdirectory} (with the latter being the default). For example: \ @@ -1826,7 +1824,7 @@ need to tweak it are not uncommon and include: \N|One type of configuration that you should normally not expose when packaging for \c{build2} is support for both header-only and compiled - modes. See \l{b#dont-header-only Don't make library header-only if it + modes. See \l{#dont-header-only Don't make library header-only if it can be compiled} for details.||| Also, in C++ projects, if you don't have any inline or template files, then @@ -2107,7 +2105,7 @@ If you only have private auto-generated headers, then only remove the expansion from \c{cxx.export.poptions}.| If you don't have any dependencies, then remove all the assignments and -expansions of the \c{intf_libs} and \c{intf_libs} variables. That is, +expansions of the \c{intf_libs} and \c{impl_libs} variables. That is, the following lines in the original \c{buildfile}: \ @@ -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. @@ -2200,7 +2198,7 @@ import impl_libs += libsqlite3%lib{sqlite3} \ \N|If you don't have any implementation or interface dependencies, you can -remove the assignment and all the expansion of the corresponding \c{*_libs} +remove the assignment and all the expansions of the corresponding \c{*_libs} variable.| Note also that system libraries like \c{-lm}, \c{-ldl} on UNIX or @@ -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 \ @@ -3703,7 +3702,7 @@ Note also that while you may be tempted to adjust the \c{version} value, resist this temptation since this will be done automatically by \l{bdep-release(1)} later. -You may also want to add the following value in certain cases: +You may also want to add the following values in certain cases: \dl| @@ -4317,6 +4316,7 @@ commit, run the following commands: \ $ cd upstream/ +$ git fetch $ git checkout v2.2.0 $ cd ../ @@ -5318,7 +5318,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 +5342,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 +5390,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}. " |