Revision: 57191
http://sourceforge.net/p/brlcad/code/57191
Author: brlcad
Date: 2013-08-28 02:18:10 +0000 (Wed, 28 Aug 2013)
Log Message:
-----------
extensive updating and expansion of the testing and debugging section in
response to tom's questions on the mailing list. explain the three types of
tests, give examples, and talk about manual testing too.
Modified Paths:
--------------
brlcad/trunk/HACKING
Modified: brlcad/trunk/HACKING
===================================================================
--- brlcad/trunk/HACKING 2013-08-28 02:13:54 UTC (rev 57190)
+++ brlcad/trunk/HACKING 2013-08-28 02:18:10 UTC (rev 57191)
@@ -42,7 +42,7 @@
Filesystem Organization
Coding Style & Standards
Documentation
- Testing
+ Testing & Debugging
Patch Submission Guidelines
Bugs & Unexpected Behavior
Commit Access
@@ -829,46 +829,76 @@
}
-TESTING
--------
+TESTING & DEBUGGING
+-------------------
-A debug build may be specified via:
+BRL-CAD has extensive testing infrastructure in place to ensure tools
+and APIs working a particular manner keep working in an expected way.
+A testing failure usually indicates an unintended change to behavior
+that must be reviewed with the provoking code justified, reverted, or
+(most commonly) fixed. There are system integration, performance,
+regression, and unit tests accessible through three primary build
+targets.
- cmake ../brlcad -DCMAKE_BUILD_TYPE=Debug
+The BRL-CAD Benchmark, contained in the bench/ directory, validates
+critical raytrace library behavior:
-A profile build may be specified via:
+ make benchmark
- cmake ../brlcad -DBRLCAD_ENABLE_PROFILING=ON
+A series of system integration regression tests, described in a series
+of scripts in the regress/ directory, examines applications:
-Verbose compilation warnings may be enabled (by default these are on):
+ make regress
- cmake ../brlcad -DBRLCAD_ENABLE_COMPILER_WARNINGS=ON
+API unit testing is contained within tests/ subdirectories of the
+respective library being tested (e.g., src/libbu/tests):
-To perform a run of the benchmark suite to validate raytrace behavior:
+ make test
- make benchmark
+Note that changes to publicly documented tools and library APIs must
+adhere to BRL-CAD's change policy. This means changes to any tests
+may require thoughtful deployment. See the CHANGES file for details.
-To perform a run of the test suite:
+To add new regression tests, look at regress/weight.sh for an
+integration test example and src/libbu/tests/bu_vls_vprintf.c for an
+API unit test example. See their corresponding CMakeLIsts.txt build
+file for examples of how they are added to the build. Individual
+regression tests have separate regress-TARGET build targets defined
+(e.g., make regress-weight) to facilitate manual testing.
- make regress
+In addition to benchmark, regression, and unit testing, individual
+programs may be tested after a build without installing by running
+them from the build directory. Typically, installed binaries will be
+found in the bin/ subdirectory of the top-level build directory, e.g.:
-To add tests, look at regress/weight.sh for an mged command example
-and regress/vls.sh for a utility function example. Each test gets
-added to the automatic execution list by creating two target entries
-in the ./regress/CMakeLists.txt: one for running the test individually
-(e.g., make regress-weight) and one for running it with all the other
-tests (make regress). Also added are the dependencies of the tests on
-binary executable rtweight and test_vls, respectively. Note also that
-each added file in the regress directory must be added to the list in
-CMAKEFILES at the bottom of file ./regress/CMakeLists.txt
+ ./bin/mged
-Individual programs may be tested after a build without installing by
-running them from the build directory. Typically, binaries will be
-found in the bin/ subdirectory of the toplevel build directory, e.g.:
+Binaries not intended for installation (i.e., marked NO_INSTALL in the
+CMakeLists.txt file) are in a build path corresponding to the source
+code location, e.g. the unit tests in src/libbu/tests compile into
+binaries in the path/to/builddir/src/libbu/tests build directory.
- ./bin/mged
+A profile build, useful for some types of performance inspection
+(e.g., gprof) but not enabled by default, may be specified via:
+ cmake .. -DBRLCAD_ENABLE_PROFILING=ON
+Debug symbols are enabled by default, even for installation, for all
+libraries and binaries in order to facilitate diagnosing and
+inspecting problems. Graceful crashes (i.e., an application "bomb")
+may result in a crash log (named appname-#####-bomb.log) getting
+written out on platforms that have the GNU Debugger (gdb) available.
+On most platforms, gdb can also be interactively utilized to inspect a
+reproducible crash (graceful or otherwise):
+
+$ gdb --args bin/mged -c file.g
+...
+gdb> break bu_bomb
+gdb> run
+...[interact with application until it crashes or bombs]
+gdb> backtrace
+
+
PATCH SUBMISSION GUIDELINES
---------------------------
This was sent by the SourceForge.net collaborative development platform, the
world's largest Open Source development site.
------------------------------------------------------------------------------
Learn the latest--Visual Studio 2012, SharePoint 2013, SQL 2012, more!
Discover the easy way to master current and previous Microsoft technologies
and advance your career. Get an incredible 1,500+ hours of step-by-step
tutorial videos with LearnDevNow. Subscribe today and save!
http://pubads.g.doubleclick.net/gampad/clk?id=58040911&iu=/4140/ostg.clktrk
_______________________________________________
BRL-CAD Source Commits mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/brlcad-commits
