Testing the build process

diff --git a/TestingBuilds.md b/TestingBuilds.md
new file mode 100644 (file)
index 0000000..9f90ef6
--- /dev/null
+++ b/TestingBuilds.md
@@ -0,0 +1,59 @@
+The installation page has a simple test process which will work most of the time to get your system up and running.  This page has more detail about running the test process to achieve various things.
+
+The base script which handles everything is the run_build.pl script.  The commandline options are:
+
+    $ ./run_build.pl --help
+    
+    usage: ./run_build.pl [options] [branch]
+    
+     where options are one or more of:
+    
+      --nosend                  = don't send results
+      --nostatus                = don't set status files
+      --force                   = force a build run (ignore status files)
+      --from-source=/path       = use source in path, not from SCM
+      or
+      --from-source-clean=/path = same as --from-source, run make distclean first
+      --config=/path/to/file    = alternative location for config file
+      --keepall                 = keep directories if an error occurs
+      --verbose[=n]             = verbosity (default 1) 2 or more = huge output.
+      --quiet                   = suppress normal error message
+      --test                    = short for --nosend --nostatus --verbose --force
+      --skip-steps=list         = skip certain steps
+      --only-steps=list         = only do certain steps, not allowed with skip-steps
+                                  lists can be comma, colon, or space separated
+    
+    Default branch is HEAD. Usually only the --config option should be necessary.
+
+### Valid Stages:
+* configure
+* make
+* build_docs  (optional, off by default)
+* make_test   (optional, off by default)
+
+In each of the following sample command lines, remember that `--test` will force all steps and will not locally store the state of the git checkout nor the state of each of stage, nor will it submit the results to the server.
+
+1. Most of the time, you probably just want to enable a feature and test if the build process changes.  In that case, this command is likely all that you'll want:
+`./run_build.pl --test --verbose=2 --only-steps=configure,make`
+
+2. Test mode, run just configure and make steps, and keep the directories:
+`./run_build.pl --test --only-steps configure,make --keepall`
+
+3. Test mode, debug mode, run just configure and make steps:
+`./run_build.pl --test --only-steps configure,make --verbose=2`
+
+4. Debug mode, only run configure and make if there is a new commit, submit results to server:
+`./run_build.pl --only-steps configure,make --verbose=2`
+
+5. Run all steps, configured to also do make_test, but limit the range of tests from 1 to 9:
+`./run_build.pl --override range_test_num='1 9'`
+
+6. Just build docs, don't submit results:
+`./run_build.pl --force --only-steps=build_docs --nosend`
+
+7. Just build docs, equivalent command:
+`./run_build.pl --test --only-steps=build_docs`
+
+8. Just build docs, but allow it to submit results:
+`./run_build.pl --force --only-steps=build_docs`
+