CVS log for src/external/bsd/atf/dist/atf-c/atf-c-api.3

Up to [cvs.NetBSD.org] / src / external / bsd / atf / dist / atf-c

Request diff between arbitrary revisions

Keyword substitution: kv
Default branch: MAIN

atf-c-api.3: correct ATF_TP_ADD_TC() examples to use "tp"

Consistent use of comma in lists.

Rebase to HEAD as of a few days ago.

sync with head.

for a reference, the tree before this commit was tagged
as yamt-pagecache-tag8.

this commit was splitted into small chunks to avoid
a limitation of cvs.  ("Protocol error: too many arguments")

Merge atf-0.19.

Import atf 0.19:

Changes in version 0.19
***********************

Experimental version released on February 7th, 2014.

This is the last release to bundle the code for the deprecated tools.
The next release will drop their code and will stop worrying about
backwards compatibility between the ATF libraries and what the old tools
may or may not support.

If you still require the old tools for some reason, grab a copy of the
'tools' directory now.  The code in this directory is standalone and
does not depend on any internal details of atf-c++ any longer.

* Various fixes and improvements to support running as part of the FreeBSD
  test suite.

* Project hosting moved from Google Code (as a subproject of Kyua) to
  GitHub (as a first-class project).  The main reason for the change is
  the suppression of binary downloads in Google Code on Jan 15th, 2014.
  See https://github.com/jmmv/atf/

* Removed builtin help from atf-sh(1) and atf-check(1) for simplicity
  reasons.  In other words, their -h option is gone.

* Moved the code of the deprecated tools into a 'tools' directory and
  completely decoupled their code from the internals of atf-c++.  The
  reason for this is to painlessly allow a third-party to maintain a
  copy of these tools after we delete them because upcoming changes to
  atf-c++ would break the stale tools.


Changes in version 0.18
***********************

Experimental version released on November 16th, 2013.

* Issue 45: Added require.memory support in atf-run for FreeBSD.

* Fixed an issue with the handling of cin with libc++.

* Issue 64: Fixed various mandoc formatting warnings.

* NetBSD PR bin/48284: Made atf-check flush its progress message to
  stdout so that an interrupted test case always shows the last message
  being executed.

* NetBSD PR bin/48285: Fixed atf_check examples in atf-sh-api(3).

resync with head

Fix merge conflicts after import of atf 0.17.

Import atf 0.17:

Experimental version released on February 14th, 2013.

* Added the atf_utils_cat_file, atf_utils_compare_file,
  atf_utils_copy_file, atf_utils_create_file, atf_utils_file_exists,
  atf_utils_fork, atf_utils_grep_file, atf_utils_grep_string,
  atf_utils_readline, atf_utils_redirect and atf_utils_wait utility
  functions to atf-c-api.  Documented the already-public
  atf_utils_free_charpp function.

* Added the cat_file, compare_file, copy_file, create_file, file_exists,
  fork, grep_collection, grep_file, grep_string, redirect and wait
  functions to the atf::utils namespace of atf-c++-api.  These are
  wrappers around the same functions added to the atf-c-api library.

* Added the ATF_CHECK_MATCH, ATF_CHECK_MATCH_MSG, ATF_REQUIRE_MATCH and
  ATF_REQUIRE_MATCH_MSG macros to atf-c to simplify the validation of a
  string against a regular expression.

* Miscellaneous fixes for manpage typos and compilation problems with
  clang.

* Added caching of the results of those configure tests that rely on
  executing a test program.  This should help crossbuild systems by
  providing a mechanism to pre-specify what the results should be.

* PR bin/45690: Make atf-report convert any non-printable characters to
  a plain-text representation (matching their corresponding hexadecimal
  entities) in XML output files.  This is to prevent the output of test
  cases from breaking xsltproc later.

Resync to 2012-11-19 00:00:00 UTC

sync with head

now sense -> no sense

sync with head

Import atf 0.15: the major goal of this import is to reconcile any local
changes to the atf codebase with upstream code.  All local changes should
have been backported, with appropriate portability workarounds where
necessary.

This new release also includes other changes though, such as performance
improvements and bug fixes, and also a major new feature partially
implemented by pgoyette@: the time to execute each test cases and test
program is now recorded and included in the output reports.

The import into NetBSD has been tested natively on amd64 and macppc, and
the full test suite has also been run through anita on amd64 and i386.
No regressions observed... but you never know.

From the NEWS file, the changes in this version are as follows:

Experimental version released on January 16th, 2012.

* Respect stdin in atf-check.  The previous release silenced stdin for any
  processes spawned by atf, not only test programs, which caused breakage
  in tests that pipe data through atf-check.

* Performance improvements to atf-sh.

* Enabled detection of unused parameters and variables in the code and
  fixed all warnings.

* Changed the behavior of "developer mode".  Compiler warnings are now
  enabled unconditionally regardless of whether we are in developer mode or
  not; developer mode is now only used to perform strict warning checks and
  to enable assertions.  Additionally, developer mode is now only
  automatically enabled when building from the repository, not for formal
  releases.

* Added new Autoconf M4 macros (ATF_ARG_WITH, ATF_CHECK_C and
  ATF_CHECK_CXX) to provide a consistent way of defining a --with-arg flag
  in configure scripts and detecting the presence of any of the ATF
  bindings.  Note that ATF_CHECK_SH was already introduced in 0.14, but it
  has now been modified to also honor --with-atf if instantiated.

* Added timing support to atf-run / atf-report.

* Added support for a 'require.memory' property, to specify the minimum
  amount of physical memory needed by the test case to yield valid results.

* PR bin/45690: Force an ISO-8859-1 encoding in the XML files generated by
  atf-report so that invalid data in the output of test cases does not
  mangle our report.

Import atf-0.13:

Experimental version released on March 31st, 2011.

This is the first release after the creation of the Kyua project, a more
modular and reliable replacement for ATF.  From now on, ATF will change to
accomodate the transition to this new codebase, but ATF will still continue
to see development in the short/medium term.  Check out the project page at
http://code.google.com/p/kyua/ for more details.

The changes in this release are:

* Added support to run the tests with the Kyua runtime engine (kyua-cli), a
  new package that aims to replace atf-run and atf-report.  The ATF tests
  can be run with the new system by issuing a 'make installcheck-kyua' from
  the top-level directory of the project (assuming the 'kyua' binary is
  available during the configuration stage of ATF).

* atf-run and atf-report are now in maintenance mode (but *not* deprecated
  yet!).  Kyua already implements a new, much more reliable runtime engine
  that provides similar features to these tools.  That said, it is not
  complete yet so all development efforts should go towards it.

* If GDB is installed, atf-run dumps the stack trace of crashing test
  programs in an attempt to aid debugging.  Contributed by Antti Kantee.

* Reverted default timeout change in previous release and reset its value
  to 5 minutes.  This was causing several issues, specially when running
  the existing NetBSD test suite in qemu.

* Fixed the 'match' output checker in atf-check to properly validate the
  last line of a file even if it does not have a newline.

* Added the ATF_REQUIRE_IN and ATF_REQUIRE_NOT_IN macros to atf-c++ to
  check for the presence (or lack thereof) of an element in a collection.

* PR bin/44176: Fixed a race condition in atf-run that would crash atf-run
  when the cleanup of a test case triggered asynchronous modifications to
  its work directory (e.g. killing a daemon process that cleans up a pid
  file in the work directory).

* PR bin/44301: Fixed the sample XSLT file to report bogus test programs
  instead of just listing them as having 0 test cases.

Import atf 0.12:

Experimental version released on November 7th, 2010.

* Added the ATF_REQUIRE_THROW_RE to atf-c++, which is the same as
  ATF_REQUIRE_THROW but allows checking for the validity of the exception's
  error message by means of a regular expression.

* Added the ATF_REQUIRE_MATCH to atf-c++, which allows checking for a
  regular expression match in a string.

* Changed the default timeout for test cases from 5 minutes to 30 seconds.
  30 seconds is long enough for virtually all tests to complete, and 5
  minutes is a way too long pause in a test suite where a single test case
  stalls.

* Deprecated the use.fs property.  While this seemed like a good idea in
  the first place to impose more control on what test cases can do, it
  turns out to be bad.  First, use.fs=false prevents bogus test cases
  from dumping core so after-the-fact debugging is harder.  Second,
  supporting use.fs adds a lot of unnecessary complexity.  atf-run will
  now ignore any value provided to use.fs and will allow test cases to
  freely access the file system if they wish to.

* Added the atf_tc_get_config_var_as_{bool,long}{,_wd} functions to the atf-c
  library.  The 'text' module became private in 0.11 but was being used
  externally to simplify the parsing of configuration variables.

* Made atf-run recognize the 'unprivileged-user' configuration variable
  and automatically drop root privileges when a test case sets
  require.user=unprivileged.  Note that this is, by no means, done for
  security purposes; this is just for user convenience; tests should, in
  general, not be blindly run as root in the first place.

Import atf 0.10:

Miscellaneous features

* Added expected failures support to test cases and atf-run.  These
  include, for example, expected clean exits, expected reception of fatal
  signals, expected timeouts and expected errors in condition checks.
  These statuses can be used to denote test cases that are known to fail
  due to a bug in the code they are testing.  atf-report reports these
  tests separately but they do not count towards the failed test cases
  amount.

* Added the ATF_CHECK_ERRNO and ATF_REQUIRE_ERRNO to the C library to
  allow easy checking of call failures that update errno.

* Added the has.cleanup meta-data property to test caes that specifies
  whether the test case has a cleanup routine or not; its value is
  automatically set.  This property is read by atf-run to know if it has to
  run the cleanup routine; skipping this run for every test case
  significantly speeds up the run time of test suites.

* Reversed the order of the ATF_CHECK_THROW macro in the C++ binding to
  take the expected exception as the first argument and the statement to
  execute as the second argument.

Changes in atf-check

* Changed atf-check to support negating the status and output checks by
  prefixing them with not- and added support to specify multiple checkers
  for stdout and stderr, not only one.

* Added the match output checker to atf-check to look for regular
  expressions in the stdout and stderr of commands.

* Modified the exit checks in atf-check to support checking for the
  reception of signals.

Code simplifications and cleanups

* Removed usage messages from test programs to simplify the
  implementation of every binding by a significant amount.  They just now
  refer the user to the appropriate manual page and do not attempt to wrap
  lines on terminal boundaries.  Test programs are not supposed to be run
  by users directly so this minor interface regression is not important.

* Removed the atf-format internal utility, which is unused after the
  change documented above.

* Removed the atf-cleanup internal utility.  It has been unused since the
  test case isolation was moved to atf-run in 0.8

* Splitted the Makefile.am into smaller files for easier maintenance and
  dropped the use of M4.  Only affects users building from the repository
  sources.

* Intermixed tests with the source files in the source tree to provide
  them more visibility and easier access.  The tests directory is gone from
  the source tree and tests are now suffixed by _test, not prefixed by t_.

* Simplifications to the atf-c library: removed the io, tcr and ui
  modules as they had become unnecessary after all simplifications
  introduced since the 0.8 release.

* Removed the application/X-atf-tcr format introduced in 0.8 release.
  Tests now print a much simplified format that is easy to parse and nicer
  to read by end users.  As a side effect, the default for test cases is
  now to print their results to stdout unless otherwise stated by providing
  the -r flag.

* Removed XML distribution documents and replaced them with plain-text
  documents.  They provided little value and introduced a lot of complexity
  to the build system.

* Simplified the output of atf-version by not attempting to print a
  revision number when building form a distfile.  Makes the build system
  easier to maintain.

Import atf 0.9:

* Added atf-sh, an interpreter to process test programs written using
  the shell API. This is not really a shell interpreter by itself
  though: it is just a wrapper around the system shell that eases the
  loading of the necessary ATF libraries.

* Removed atf-compile in favour of atf-sh.

* Added the use.fs metadata property to test case, which is used to
  specify which test cases require file system access. This is to
  highlight dependencies on external resources more clearly and to speed
  up the execution of test suites by skipping the creation of many
  unnecessary work directories.

* Fixed test programs to get a sane default value for their source
  directory. This means that it should not be necessary any more to pass
  -s when running test programs that do not live in the current
  directory.

* Defining test case headers became optional. This is trivial to achieve
  in shell-based tests but a bit ugly in C and C++. In C, use the new
  ATF_TC_WITHOUT_HEAD macro to define the test case, and in C++ use
  ATF_TEST_CASE_WITHOUT_HEAD.

Import atf 0.7.  Changes in this release:

* Added build-time checks to atf-c and atf-c++.  A binding for atf-sh
  will come later.

* Migrated all build-time checks for header files to proper ATF tests.
  This demonstrates the use of the new feature described above.

* Added an internal API for child process management.

* Converted all plain-text distribution documents to a Docbook canonical
  version, and include pre-generated plain text and HTML copies in the
  distribution file.

* Simplified the contents of the Makefile.am by regenerating it from a
  canonical Makefile.am.m4 source.  As a side-effect, some dependency
  specifications were fixed.

* Migrated all checks from the check target to installcheck, as these
  require ATF to be installed.

* Fixed sign comparison mismatches triggered by the now-enabled
  -Wsign-compare.

* Fixed many memory and object leaks.

Import ATF 0.6.  Replaces the old ATF 0.5 that was in dist/atf.

Changes in this release:

* Make atf-exec be able to kill its child process after a certain period of
  time; this is controlled through the new -t option.

* Change atf-sh to use atf-exec's -t option to control the test case's
  timeouts, instead of doing it internally.  Same behavior as before, but
  noticeably faster.

* atf-exec's -g option and atf-killpg are gone due to the previous change.

* Added the atf-check(1) tool, a program that executes a given command and
  checks its exit code against a known value and allows the management of
  stdout and stderr in multiple ways.  This replaces the previous atf_check
  function in the atf-sh library and exposes this functionality to both
  atf-c and atf-c++.

* Added the ATF_REQUIRE family of macros to the C interface.  These help
  in checking for fatal test conditions.  The old ATF_CHECK macros now
  perform non-fatal checks only.  I.e. by using ATF_CHECK, the test case
  can now continue its execution and the failures will not be reported
  until the end of the whole run.

* Extended the amount of ATF_CHECK_* C macros with new ones to provide more
  features to the developer.  These also have their corresponding
  counterparts in the ATF_REQUIRE_* family.  The new macros (listing the
  suffixes only) are: _EQ (replaces _EQUAL), _EQ_MSG, _STREQ and
  _STREQ_MSG.

Initial revision