libs/test/doc/prod_use/program_execution_monitor.qbk

   1 [/
   2  / Copyright (c) 2003 Boost.Test contributors
   3  /
   4  / Distributed under the Boost Software License, Version 1.0. (See accompanying
   5  / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   6  /]
   7
   8 [/ ##################################################################### ]
   9
  10 [section:pem Program Execution Monitor]
  11
  12 The components of a C++ program may report user-detected errors in several ways, such as via a return value or
  13 throwing an exception. System-detected errors such as dereferencing an invalid pointer are reported in other ways,
  14 totally operating system and compiler dependent.
  15
  16 Yet many C++ programs, both production and test, must run in an environment where uniform reporting of errors is
  17 necessary. For example, converting otherwise uncaught exceptions to non-zero program return codes allows many
  18 command line, script, or batch environments to continue processing in a controlled manner. Even some
  19 ['GUI] environments benefit from the unification of errors into program return codes.
  20
  21
  22 The Boost.Test Library's *Program Execution Monitor* relieves users from messy error
  23 detection and reporting duties by providing a replacement function `main()` which calls a user-supplied `cpp_main()`
  24 function within a monitored environment. The supplied `main()` then uniformly detects and reports the occurrence of
  25 several types of errors, reducing them to a uniform return code which is returned to the host environment.
  26
  27 Uniform error reporting is particularly useful for programs running unattended under control of scripts or batch
  28 files. Some operating systems pop up message boxes if an uncaught exception occurs, and this requires manual
  29 intervention. By converting such exceptions into non-zero program return codes, the library makes the program a
  30 better citizen. More uniform reporting of errors isn't a benefit to some programs, particularly programs always
  31 run by hand of a knowledgeable person. So the __PEM__ wouldn't be worth using in that environment.
  32
  33 Uniform error reporting can be also useful in test environments such as the Boost
  34 regression tests. Be aware though in such case it might be preferable to use the
  35 __UTF__, because it allows one to use the
  36 [link boost_test.testing_tools testing tools] and generate more detailed
  37 error information.
  38
  39 [section Usage]
  40
  41 To facilitate uniform error reporting the __PEM__ supplies function `main()` as part if it's implementation. To use the
  42 __PEM__ instead of regular function `main` your program is required to supply a function `cpp_main()` with same signature.
  43
  44 Here is the traditional ['Hello World] program implemented using the __PEM__:
  45
  46 [bt_example example24..Hello World with the Program Execution Monitor..run-fail]
  47
  48 It really is that simple - just change the name of your initial function from `main()` to `cpp_main()`. Do make sure
  49 the `argc` and `argv` parameters are specified (although you don't have to name them if you don't use them).
  50
  51 The __PEM__ treats as errors:
  52
  53 * Exceptions thrown from `cpp_main()`
  54 * Non-zero return from `cpp_main()`
  55
  56 So what if some function had thrown a `std::runtime_error` with the message "big trouble" and it is not trapped by any
  57 catch clause? Like in a following example:
  58
  59 [bt_example example25..Standard exception detection within the __PEM__..run-fail]
  60
  61 [note Note that in both examples above we used [link boost_test.components.section_pem.section_pem_compilation.section_pem_full_include header-only variant]
  62 of the __PEM__. Alternatively the binaries may be built and linked with
  63 a [link boost_test.components.section_pem.section_pem_compilation.section_pem_standalone standalone library] (in case of static library we are not required to include any __PEM__ related headers).
  64 ]
  65
  66 Let's consider an example where function `cpp_main()` had bubbled up a return code of 5:
  67
  68 [bt_example example26..Error return code detection of the __PEM__..run-fail]
  69
  70 The __PEM__ reports errors to both `std::cout` (details) and `std::cerr` (summary). Primary detailed error
  71 messages appear on standard output stream so that it is properly interlaced with other output, thus aiding error
  72 analysis. While the final error notification message appears on standard error stream. This increases the
  73 visibility of error notification if standard output and error streams are directed to different devices or files.
  74
  75 The __PEM__'s supplied `main()` will return following result codes:
  76
  77 * `boost::exit_success` - no errors
  78 * `boost::exit_failure` - non-zero and `non-boost::exit_success` return code from `cpp_main()`
  79 * `boost::exit_exception_failure` - `cpp_main()` throw an exception
  80
  81 [endsect] [/ Usage]
  82
  83
  84
  85 [/ ####################################################################################  configuration]
  86 [section Runtime configuration]
  87
  88 There are two aspects of the __PEM__ behavior that you can customize at runtime. Customization is performed using
  89 environment variables.
  90
  91 [table:id_pem_env The __PEM__ configuration environment variables
  92   [
  93     [Flag]
  94     [Usage]
  95   ]
  96   [
  97     [`BOOST_TEST_CATCH_SYSTEM_ERRORS`]
  98     [allows customizing behavior of the __PEM__ in regards of catching system errors. For more details about the
  99      meaning of this option see the [classref boost::execution_monitor execution_monitor] class. If you
 100      want to prevent the __PEM__ from catching system exception, set the value of this
 101      variable to "no". The default value is "yes".]
 102   ]
 103   [
 104     [`BOOST_PRG_MON_CONFIRM`]
 105     [allows avoiding success confirmation message. Some users prefer to see a confirmation message in case if program
 106        successfully executed. While others don't like the clutter or any output is prohibited by organization standards.
 107        To avoid the message set the value of this variable to "no". The default value is "yes".]
 108   ]
 109
 110 ]
 111
 112 [note `BOOST_TEST_CATCH_SYSTEM_ERRORS` is similar to the __UTF__'s
 113  [link boost_test.utf_reference.rt_param_reference.catch_system `catch_system_error`] command line parameter.]
 114
 115 [endsect] [/ configuration]
 116
 117 [/ ####################################################################################  implementation]
 118 [#ref_pem_implementation][section Implementation]
 119
 120 To monitor execution of user supplied function `cpp_main()` the __PEM__ relies on the Boost.Test's
 121 [link boost_test.components.execution_monitor Execution Monitor]. Also the __PEM__ supplies the function `main()` to facilitate
 122 uniform error reporting. Following files constitute the __PEM__ implementation:
 123
 124
 125 [table:pem_implementation_file __PEM__ implementation files
 126
 127   [
 128     [File name]
 129     [Content]
 130   ]
 131   [
 132     [`boost/test/impl/execution_monitor.ipp`]
 133     [provides __EM__ implementation for all supported configurations]
 134   ]
 135   [
 136     [`boost/test/impl/cpp_main.ipp`]
 137     [supplies function `main()` for static library build]
 138   ]
 139   [
 140     [`boost/test/included/prg_exec_monitor.hpp`]
 141     [combines all implementation files into single header to be use as inlined version of component]
 142   ]
 143   [
 144     [`boost/test/prg_exec_monitor.hpp`]
 145     [contains definitions for `main()` function for dynamic library build and pragmas for auto-linking feature support]
 146   ]
 147 ]
 148
 149 The __PEM__ implementation wraps several system headers and is intended to be used as standalone library. While there
 150 exist an alternative variant to [link ref_pem_direct_include include the whole implementation
 151 directly] into your program, for the long term usage the preferable solution is to
 152 [link ref_pem_stanlone build library once] and reuse it.
 153
 154
 155 [endsect] [/implementation]
 156
 157 [section:section_pem_compilation Compilation]
 158
 159 In comparison with many other boost libraries, which are completely implemented in header files, compilation and
 160 linking with the __PEM__ may require additional steps. The __PEM__ presents you with options to either
 161
 162 # built and link with a [link ref_pem_stanlone standalone library] or
 163 # include the implementation [link ref_pem_direct_include directly] into your program.
 164
 165 If you opt to use the library the __PEM__ header implements the
 166 [*auto-linking support] and following flags can be used to configure
 167 compilation of the __PEM__ library and your program:
 168
 169 [table
 170   [
 171     [Variable]
 172     [Usage]
 173   ]
 174   [
 175     [__BOOST_TEST_DYN_LINK__]
 176     [Define this flag to build/use dynamic library]
 177   ]
 178   [
 179     [__BOOST_TEST_NO_LIB__]
 180     [Define this flag to prevent auto-linking]
 181   ]
 182 ]
 183
 184 [#ref_pem_stanlone][section:section_pem_standalone Standalone library compilation]
 185
 186 If you opted to link your program with the standalone library, you need to build it first. To build a standalone
 187 library all C++ files (.cpp), that constitute __PEM__ [link ref_pem_implementation implementation] need to be
 188 listed as source files in your makefile [footnote There are varieties of make systems that can be used. To name
 189 a few: ['GNU] make (and other make clones) and build systems integrated into ['IDE]s
 190 (for example ['Microsoft Visual Studio]). The Boost preferred solution is Boost.Build system that is based on top of
 191 `b2`  tool. Make  systems require some kind of configuration file that lists all files that constitute the library
 192 and all build  options. For example the makefile that is used by make, or the Microsoft Visual Studio project file,
 193 Jamfile is used by Boost.Build. For the sake of simplicity let's call this file the makefile.].
 194
 195
 196 The makefile for use with Boost.Build system is supplied in
 197
 198 ``
 199 libs/test/build
 200 ``
 201
 202 directory. The __PEM__ can be built as either [link ref_pem_static static] or [link ref_pem_dynamic dynamic] library.
 203
 204
 205
 206 [#ref_pem_static][section:section_pem_compilation_static Static library compilation]
 207
 208 There are no additional build defines or options required to build static library. Using Boost.Build system you
 209 can build the static library with a following command from `libs/test/build` directory:
 210
 211 ``
 212 b2 -sTOOLS=<your-tool-name> -sBUILD=boost_prg_exec_monitor
 213 ``
 214
 215 Also on Windows you can use the Microsoft Visual Studio .NET project file provided.
 216
 217 [endsect] [/ static compilation]
 218
 219 [#ref_pem_dynamic][section:section_pem_compilation_dynamic Dynamic library compilation]
 220
 221 To build the dynamic library [footnote What is meant by the term dynamic library is a ['dynamically
 222 loaded library], alternatively called a ['shared library].] you
 223 need to add __BOOST_TEST_DYN_LINK__ to the list of macro definitions in the
 224 ``libs/test/build`` directory:
 225
 226 ``
 227 b2 -sTOOLS=<your-tool-name> -sBUILD=boost_prg_exec_monitor
 228 ``
 229
 230 Also on Windows you can use the Microsoft Visual Studio .NET project file provided.
 231
 232 [caution
 233   For your program to successfully link with the dynamic library the flag
 234   __BOOST_TEST_DYN_LINK__ needs to be defined both during dynamic library
 235   build and during your program compilation.
 236 ]
 237
 238
 239 [endsect] [/ dynamic compilation]
 240 [endsect] [/ standalone lib compilation]
 241
 242 [#ref_pem_auto_link][section Support of the auto-linking feature]
 243
 244
 245 For the Microsoft family of compilers the __PEM__ provides an ability to automatically select proper library name
 246 and add it to the list of objects to be linked with. To employ this feature you required to include either header
 247
 248 ``
 249 #include <boost/test/prg_exec_monitor.hpp>
 250 ``
 251 or header
 252
 253 ``
 254 #include <boost/test/included/prg_exec_monitor.hpp>
 255 ``
 256
 257 By default the feature is enabled. To disable it you have to define the flag __BOOST_TEST_NO_LIB__.
 258
 259
 260 [endsect] [/ autolink]
 261
 262 [#ref_pem_direct_include][section:section_pem_full_include Including the __PEM__ directly into your program]
 263
 264 If you prefer to avoid the standalone library compilation you have two alternative usage variants: you can either
 265 include all files that constitute the static library in your program's makefile or include them as a part of
 266 your program's source file. To facilitate the later variant the __PEM__ implementation presents the header
 267 ``
 268 #include <boost/test/included/prg_exec_monitor.hpp>
 269 ``
 270
 271 In both variants neither __BOOST_TEST_DYN_LINK__ nor __BOOST_TEST_NO_LIB__ are applicable. This solution may not be the best choice
 272 in a long run, since it requires the __PEM__ sources recompilation for every program you use it with.
 273
 274 [endsect] [/ direct include]
 275
 276
 277 [endsect] [/compilation]
 278
 279
 280
 281 [endsect] [/program execution monitor]