diff options
| -rw-r--r-- | doc/packaging.cli | 111 |
1 files changed, 105 insertions, 6 deletions
diff --git a/doc/packaging.cli b/doc/packaging.cli index 201b336..c3e4747 100644 --- a/doc/packaging.cli +++ b/doc/packaging.cli @@ -2241,19 +2241,118 @@ Use if upstream relies on source code generators, such as See the \c{build2} HOWTO article collection for more unusual requirements.|| +@@ TODO: build the library only here? Can't test since smoke test might be not +configurable. Doesn't feel sensible to commit a potentially broken smoke +test, but maybe. -@@ Note on library metadata where talk about configuration. Also about - autoconf. +@@ Show how to sync with config vars? Actually, can't do without fixing +up smoke test first. Unless do it right after adding imports for +dependencies and before modifying the rest of src buildfile. -@@ Commit? Can't test since smoke test might be not configurable. -======== +\h#core-test-smoke|Make smoke test| -@@ Show how to sync with config vars? Actually, can't do without fixing -up smoke test first. +With the library build sorted, we need tests to make sure it is actually +functional. As \l{#core-fill discussed earlier}, it is recommended to start +with a simple smoke test, make sure that works, and then replace it with +upstream tests. However, if upstream tests look simple enough, you can skip +the smoke test. For example, if upstream has all its tests in a single source +file and its build doesn't look too complicated, then you can just use that +source file in place of the smoke test. + +\N|If upstream has no tests, then the smoke test will have to stay. A library +can only be published if it has at least one test. + +It is also recommended to have the smoke test if upstream tests are in a +separate package. See +\l{https://github.com/build2/HOWTO/blob/master/entries/handle-tests-with-extra-dependencies.md +How do I handle tests that have extra dependencies?} for background and +details.| + +To recap, the \c{bdep-new}-generated \c{tests/} subdirectory looks like this +(continuing with our \c{libfoo} example): + +\ +libfoo/ +├── ... +└── tests/ + ├── build/ + │ ├── bootstrap.build + │ └── root.build + ├── basics/ + │ ├── driver.cpp + │ └── buildfile + └── buildfile +\ + +The \c{tests/} subdirectory is a build system subproject, meaning that it can +be built independently, for example, to test the installed version of the +library (see \l{b#intro-operations-test Testing} for background). In +particular, this means it has the \c{build/} subdirectory with project-wide +build system files the same as our library. Then there is the \c{basics/} +subdirectory which contains the generated test and which is what we will be +turning into a smoke test. The subproject root \c{buildfile} rarely needs +changing. + +\h2#core-test-smoke-build-wide|Review project-wide build system files in \c{tests/build/}| + +Review the generated \c{bootstrap.build} and \c{root.build} (there will be no +\c{export.build}) similar to \l{#core-adjust-build-wide Review project-wide +build system files in \c{build/}}. + +Here the only change you would normally make is in \c{root.build} to drop the +assignment of extensions for target types that are not used in tests. + + +\h2#core-test-smoke-adjust|Convert generated test to library smoke test| + +The \c{basics/} subdirectory contains the \c{driver.cpp} source file that +implements the test and \c{buildfile} that builds it. You can rename both the +test directory (\c{basics/}) and the source file \c{driver.cpp}, for example, +if you are going with the upstream tests directly. You can also add more tests +by simply copying \c{basics/}. + +The purpose of a smoke test is to make sure the library's public headers can +be included (including in the installed case, no pun intended), it can be +linked, and its basic functionality works. + +To achieve this, we modify \c{driver.cpp} to include the library's main +headers and call a few functions. For example, if the library has the +init/deinit type of functions, those are good candidates to call. If the +library is not header-only, make sure that the smoke test calls at least one +non-inline/template function to test symbol exporting. + +Continuing with our \c{libfoo} example, this is what its smoke test might look +like: + +\ +#include <foo/core.hpp> +#include <foo/util.hpp> + +#undef NDEBUG +#include <cassert> + +int main () +{ + foo::context* c (foo::init (0 /* flags */)); + assert (c != nullptr); + foo::deinit (c); +} +\ + +\N|The C/C++ \c{assert()} macro is often an adequate \"testing framework\" for +simple tests and does not require extra dependencies. But see +\l{https://github.com/build2/HOWTO/blob/master/entries/use-assert-in-tests.md +How do I correctly use C/C++ assert() in tests?}| + + +@@ Next: test locally, commit, test with CI. ======== +@@ Note on library metadata where talk about configuration. Also about + autoconf. + @@ Use of the version module and non-semver versions? Links to HOWTO entries! @@ Squash commits? |