diff options
Diffstat (limited to 'doc/packaging.cli')
| -rw-r--r-- | doc/packaging.cli | 72 |
1 files changed, 72 insertions, 0 deletions
diff --git a/doc/packaging.cli b/doc/packaging.cli index db98c1d..356cfc4 100644 --- a/doc/packaging.cli +++ b/doc/packaging.cli @@ -100,6 +100,78 @@ normally be possible to move/rename the top-level \c{tests/} directory or to place the library source directory into a subdirectory. +\h#dont-forget-update-manifest|Don't forget to update \c{manifest} values| + +After \l{#dont-from-scratch generating the project template with \c{bdep-new}}, +don't forget to update at least the key values in the generated \c{manifest}: +\c{version}, \c{license}, and \c{summary}. + +For \c{version}, use the upstream version directly if it is semver (or +semver-like, that is, has three version components). Otherwise, see +\l{https://github.com/build2/HOWTO/blob/master/entries/handle-projects-which-dont-use-semver.md +How do I handle projects that don't use semantic versioning?} and +\l{https://github.com/build2/HOWTO/blob/master/entries/handle-projects-which-dont-use-version.md +How do I handle projects that don't use versions at all?} + +For \c{license}, use the \l{https://spdx.org/licenses/ SPDX license ID} if at +all possible. If multiple licenses are involved, use the SPDX License +expression. See the +\l{https://build2.org/bpkg/doc/build2-package-manager-manual.xhtml#manifest-package-license +\c{license} manifest value} documentation for details and the list of the +most commonly used SPDX license IDs. + +For \c{summary} use a brief description of the functionality provided by the +package. Less than 70 characters is a good target to aim for. Don't capitalize +subsequent words unless proper nouns and omit the trailing dot. For example: + +\ +summary: Vim xxd hexdump utility +\ + +Omit weasel words such as \"modern\", \"simple\", \"fast\", \"small\", etc., +since they don't convey anything specific. Omit \"header-only\" or +\"single-header\" for C/C++ libraries since at least in the context of +\c{build2} it does not imply any advantage. + +If upstream does not offer a sensible summary, the following template is +recommended for libraries: + +\ +summary: <functionality> C library +summary: <functionality> C++ library +\ + +For example: + +\ +summary: Event notification C library +summary: Validating XML parsing and serialization C++ library +\ + +If the project consists of multiple packages it may be tempting to name each +package in terms of the overall project name, for example: + +\ +summary: libigl's core module +\ + +This doesn't give the user any clue about what functionality is provided +unless they find out what \c{libigl} is about. Better: + +\ +summary: Geometry processing C++ library, core module +\ + +If you follow the above pattern, then to produce a summary for external tests +or examples packages simply add \"tests\" or \"examples\" at the end, +for example: + +\ +summary: Event notification C library tests +summary: Geometry processing C++ library, core module examples +\ + + \h#dont-header-only|Don't make a library header-only if it can be compiled| Some libraries offer two alternative modes: header-only and compiled. Unless |