diff options
Diffstat (limited to 't/data/generate/c-tap-harness/docknot.yaml')
| -rw-r--r-- | t/data/generate/c-tap-harness/docknot.yaml | 272 |
1 files changed, 134 insertions, 138 deletions
diff --git a/t/data/generate/c-tap-harness/docknot.yaml b/t/data/generate/c-tap-harness/docknot.yaml index d16c14e..8a74885 100644 --- a/t/data/generate/c-tap-harness/docknot.yaml +++ b/t/data/generate/c-tap-harness/docknot.yaml @@ -112,144 +112,6 @@ description: | files, creating temporary files, reporting output from external programs running in the background, and similar common problems. -readme: - sections: - - title: Testing - body: | - C TAP Harness comes with a comprehensive test suite, which you can - run after building with: - - ``` - make check - ``` - - If a test fails, you can run a single test with verbose output via: - - ``` - ./runtests -b `pwd`/tests -s `pwd`/tests -o <name-of-test> - ``` - - Do this instead of running the test program directly since it will - ensure that necessary environment variables are set up. You may - need to change the `-s` option argument if you build with a - separate build directory from the source directory. - - title: Using the Harness - body: | - While there is an install target that installs runtests in the - default binary directory (`/usr/local/bin` by default) and - installs the man pages, one normally wouldn't install anything - from this package. Instead, the code is intended to be copied - into your package and refreshed from the latest release of C TAP - Harness for each release. - - You can obviously copy the code and integrate it however works - best for your package and your build system. Here's how I do it - for my packages as an example: - - * Create a tests directory and copy tests/runtests.c into it. - Create a `tests/tap` subdirectory and copy the portions of the - TAP library (from `tests/tap`) that I need for that package into - it. The TAP library is designed to let you drop in additional - source and header files for additional utility functions that - are useful in your package. - - * Add code to my top-level `Makefile.am` (I always use a - non-recursive Makefile with `subdir-objects` set) to build - `runtests` and the test library: - - ```make - check_PROGRAMS = tests/runtests - tests_runtests_CPPFLAGS = -DC_TAP_SOURCE='"$(abs_top_srcdir)/tests"' \ - -DC_TAP_BUILD='"$(abs_top_builddir)/tests"' - check_LIBRARIES = tests/tap/libtap.a - tests_tap_libtap_a_CPPFLAGS = -I$(abs_top_srcdir)/tests - tests_tap_libtap_a_SOURCES = tests/tap/basic.c tests/tap/basic.h \ - tests/tap/float.c tests/tap/float.h tests/tap/macros.h - ``` - - Omit `float.c` and `float.h` from the last line if your package - doesn't need the `is_double` function. Building the build and - source directories into runtests will let `tests/runtests -o - <test>` work for users without requiring that they set any other - variables, even if they're doing an out-of-source build. - - Add additional source files and headers that should go into the - TAP library if you added extra utility functions for your - package. - - * Add code to `Makefile.am` to run the test suite: - - ```make - check-local: $(check_PROGRAMS) - cd tests && ./runtests -l $(abs_top_srcdir)/tests/TESTS - ``` - - See the `Makefile.am` in this package for an example. - - * List the test programs in the `tests/TESTS` file. This should - have the name of the test executable with the trailing "-t" or - ".t" (you can use either extension as you prefer) omitted. - - Test programs must be executable. - - For any test programs that need to be compiled, add build rules - for them in `Makefile.am`, similar to: - - ```make - tests_libtap_c_basic_LDADD = tests/tap/libtap.a - ``` - - and add them to `check_PROGRAMS`. If you include the `float.c` - add-on in your libtap library, you will need to add `-lm` to the - `_LDADD` setting for all test programs linked against it. - - A more complex example from the remctl package that needs - additional libraries: - - ```make - tests_client_open_t_LDFLAGS = $(GSSAPI_LDFLAGS) - tests_client_open_t_LDADD = client/libremctl.la tests/tap/libtap.a \ - util/libutil.la $(GSSAPI_LIBS) - ``` - - If the test program doesn't need to be compiled, add it to - `EXTRA_DIST` so that it will be included in the distribution. - - * If you have test programs written in shell, copy - `tests/tap/libtap.sh` the tap subdirectory of your tests - directory and add it to `EXTRA_DIST`. Shell programs should - start with: - - ```sh - . "${C_TAP_SOURCE}/tap/libtap.sh" - ``` - - and can then use the functions defined in the library. - - * Optionally copy `docs/writing-tests` into your package - somewhere, such as `tests/README`, as instructions to - contributors on how to write tests for this framework. - - If you have configuration files that the user must create to - enable some of the tests, conventionally they go into - `tests/config`. - - If you have data files that your test cases use, conventionally - they go into `tests/data`. You can then find the data directory - relative to the `C_TAP_SOURCE` environment variable (set by - `runtests`) in your test program. If you have data that's - compiled or generated by Autoconf, it will be relative to the - `BUILD` environment variable. Don't forget to add test data to - `EXTRA_DIST` as necessary. - - For more TAP library add-ons, generally ones that rely on - additional portability code not shipped in this package or with - narrower uses, see [the rra-c-util - package](https://www.eyrie.org/~eagle/software/rra-c-util/). - There are several additional TAP library add-ons in the - `tests/tap` directory in that package. It's also an example of - how to use this test harness in another package. - requirements: | C TAP Harness requires a C compiler to build. Any ISO C89 or later C compiler on a system supporting the Single UNIX Specification, version 3 @@ -267,3 +129,137 @@ requirements: | All are available on CPAN. Those tests will be skipped if the modules are not available. + +sections: + - title: Using the Harness + body: | + While there is an install target that installs runtests in the + default binary directory (`/usr/local/bin` by default) and installs + the man pages, one normally wouldn't install anything from this + package. Instead, the code is intended to be copied into your + package and refreshed from the latest release of C TAP Harness for + each release. + + You can obviously copy the code and integrate it however works best + for your package and your build system. Here's how I do it for my + packages as an example: + + * Create a tests directory and copy tests/runtests.c into it. + Create a `tests/tap` subdirectory and copy the portions of the TAP + library (from `tests/tap`) that I need for that package into it. + The TAP library is designed to let you drop in additional source + and header files for additional utility functions that are useful + in your package. + + * Add code to my top-level `Makefile.am` (I always use a + non-recursive Makefile with `subdir-objects` set) to build + `runtests` and the test library: + + ```make + check_PROGRAMS = tests/runtests + tests_runtests_CPPFLAGS = -DC_TAP_SOURCE='"$(abs_top_srcdir)/tests"' \ + -DC_TAP_BUILD='"$(abs_top_builddir)/tests"' + check_LIBRARIES = tests/tap/libtap.a + tests_tap_libtap_a_CPPFLAGS = -I$(abs_top_srcdir)/tests + tests_tap_libtap_a_SOURCES = tests/tap/basic.c tests/tap/basic.h \ + tests/tap/float.c tests/tap/float.h tests/tap/macros.h + ``` + + Omit `float.c` and `float.h` from the last line if your package + doesn't need the `is_double` function. Building the build and + source directories into runtests will let `tests/runtests -o + <test>` work for users without requiring that they set any other + variables, even if they're doing an out-of-source build. + + Add additional source files and headers that should go into the + TAP library if you added extra utility functions for your package. + + * Add code to `Makefile.am` to run the test suite: + + ```make + check-local: $(check_PROGRAMS) + cd tests && ./runtests -l $(abs_top_srcdir)/tests/TESTS + ``` + + See the `Makefile.am` in this package for an example. + + * List the test programs in the `tests/TESTS` file. This should + have the name of the test executable with the trailing "-t" or + ".t" (you can use either extension as you prefer) omitted. + + Test programs must be executable. + + For any test programs that need to be compiled, add build rules + for them in `Makefile.am`, similar to: + + ```make + tests_libtap_c_basic_LDADD = tests/tap/libtap.a + ``` + + and add them to `check_PROGRAMS`. If you include the `float.c` + add-on in your libtap library, you will need to add `-lm` to the + `_LDADD` setting for all test programs linked against it. + + A more complex example from the remctl package that needs + additional libraries: + + ```make + tests_client_open_t_LDFLAGS = $(GSSAPI_LDFLAGS) + tests_client_open_t_LDADD = client/libremctl.la tests/tap/libtap.a \ + util/libutil.la $(GSSAPI_LIBS) + ``` + + If the test program doesn't need to be compiled, add it to + `EXTRA_DIST` so that it will be included in the distribution. + + * If you have test programs written in shell, copy + `tests/tap/libtap.sh` the tap subdirectory of your tests directory + and add it to `EXTRA_DIST`. Shell programs should start with: + + ```sh + . "${C_TAP_SOURCE}/tap/libtap.sh" + ``` + + and can then use the functions defined in the library. + + * Optionally copy `docs/writing-tests` into your package somewhere, + such as `tests/README`, as instructions to contributors on how to + write tests for this framework. + + If you have configuration files that the user must create to enable + some of the tests, conventionally they go into `tests/config`. + + If you have data files that your test cases use, conventionally they + go into `tests/data`. You can then find the data directory relative + to the `C_TAP_SOURCE` environment variable (set by `runtests`) in + your test program. If you have data that's compiled or generated by + Autoconf, it will be relative to the `BUILD` environment variable. + Don't forget to add test data to `EXTRA_DIST` as necessary. + + For more TAP library add-ons, generally ones that rely on additional + portability code not shipped in this package or with narrower uses, + see [the rra-c-util + package](https://www.eyrie.org/~eagle/software/rra-c-util/). There + are several additional TAP library add-ons in the `tests/tap` + directory in that package. It's also an example of how to use this + test harness in another package. + +test: + override: | + C TAP Harness comes with a test suite, which you can run after + building with: + + ``` + make check + ``` + + If a test fails, you can run a single test with verbose output via: + + ``` + ./runtests -b `pwd`/tests -s `pwd`/tests -o <name-of-test> + ``` + + Do this instead of running the test program directly since it will + ensure that necessary environment variables are set up. You may need + to change the `-s` option argument if you build with a separate build + directory from the source directory. |