1@menu 2* Functions and Variables for Bug Detection and Reporting:: 3@end menu 4 5@c ----------------------------------------------------------------------------- 6@node Functions and Variables for Bug Detection and Reporting 7@section Functions and Variables for Bug Detection and Reporting 8@c ----------------------------------------------------------------------------- 9 10@c ----------------------------------------------------------------------------- 11@anchor{run_testsuite} 12@deffn {Function} run_testsuite ([@var{options}]) 13 14Run the Maxima test suite. Tests producing the desired answer are 15considered ``passes,'' as are tests that do not produce the desired 16answer, but are marked as known bugs. 17 18@code{run_testsuite} takes the following optional keyword arguments 19 20@table @code 21@item display_all 22Display all tests. Normally, the tests are not displayed, unless the test 23fails. (Defaults to @code{false}). 24@item display_known_bugs 25Displays tests that are marked as known bugs. (Default is @code{false}). 26@item tests 27This is a single test or a list of tests that should be run. Each test can be specified by 28either a string or a symbol. By default, all tests are run. The complete set 29of tests is specified by @mrefdot{testsuite_files} 30@item time 31Display time information. If @code{true}, the time taken for each 32test file is displayed. If @code{all}, the time for each individual 33test is shown if @code{display_all} is @code{true}. The default is 34@code{false}, so no timing information is shown. 35@item share_tests 36Load additional tests for the @code{share} directory. If @code{true}, 37these additional tests are run as a part of the testsuite. If 38@code{false}, no tests from the @code{share} directory are run. If 39@code{only}, only the tests from the @code{share} directory are run. 40Of course, the actual set of test that are run can be controlled by 41the @code{tests} option. The default is @code{false}. 42@end table 43 44For example @code{run_testsuite(display_known_bugs = true, tests=[rtest5])} 45runs just test @code{rtest5} and displays the test that are marked as 46known bugs. 47 48@code{run_testsuite(display_all = true, tests=["rtest1", rtest1a])} will 49run tests @code{rtest1} and @code{rtest2}, and displays each test. 50 51@code{run_testsuite} changes the Maxima environment. 52Typically a test script executes @mref{kill} to establish a known environment 53(namely one without user-defined functions and variables) 54and then defines functions and variables appropriate to the test. 55 56@code{run_testsuite} returns @code{done}. 57 58@opencatbox 59@category{Debugging} 60@closecatbox 61@end deffn 62 63@c ----------------------------------------------------------------------------- 64@anchor{testsuite_files} 65@defvr {Option variable} testsuite_files 66 67@code{testsuite_files} is the set of tests to be run by 68@mrefdot{run_testsuite} It is a list of names of the files containing 69the tests to run. If some of the tests in a file are known to fail, 70then instead of listing the name of the file, a list containing the 71file name and the test numbers that fail is used. 72 73For example, this is a part of the default set of tests: 74 75@example 76 ["rtest13s", ["rtest14", 57, 63]] 77@end example 78 79This specifies the testsuite consists of the files "rtest13s" and 80"rtest14", but "rtest14" contains two tests that are known to fail: 57 81and 63. 82 83@opencatbox 84@category{Debugging} 85@category{Global variables} 86@closecatbox 87@end defvr 88 89@defvr {Option variable} share_testsuite_files 90 91@code{share_testsuite_files} is the set of tests from the @code{share} 92directory that is run as a part of the test suite by 93@mrefdot{run_testsuite}. 94 95@opencatbox 96@category{Debugging} 97@category{Global variables} 98@closecatbox 99@end defvr 100 101@c ----------------------------------------------------------------------------- 102@anchor{bug_report} 103@deffn {Function} bug_report () 104 105Prints out Maxima and Lisp version numbers, and gives a link 106to the Maxima project bug report web page. 107The version information is the same as reported by @mrefdot{build_info} 108 109When a bug is reported, it is helpful to copy the Maxima 110and Lisp version information into the bug report. 111 112@code{bug_report} returns an empty string @code{""}. 113 114@opencatbox 115@category{Debugging} 116@closecatbox 117@end deffn 118 119@c ----------------------------------------------------------------------------- 120@anchor{build_info} 121@deffn {Function} build_info () 122 123Returns a summary of the parameters of the Maxima build, 124as a Maxima structure (defined by @code{defstruct}). 125The fields of the structure are: 126@code{version}, @code{timestamp}, @code{host}, @code{lisp_name}, and @code{lisp_version}. 127When the pretty-printer is enabled (via @code{display2d}), 128the structure is displayed as a short table. 129 130See also @mrefdot{bug_report} 131 132Examples: 133 134@c ===beg=== 135@c build_info (); 136@c x : build_info ()$ 137@c x@version; 138@c x@timestamp; 139@c x@host; 140@c x@lisp_name; 141@c x@lisp_version; 142@c x; 143@c ===end=== 144@example 145@group 146(%i1) build_info (); 147(%o1) 148Maxima version: "5.36.1" 149Maxima build date: "2015-06-02 11:26:48" 150Host type: "x86_64-unknown-linux-gnu" 151Lisp implementation type: "GNU Common Lisp (GCL)" 152Lisp implementation version: "GCL 2.6.12" 153@end group 154(%i2) x : build_info ()$ 155@group 156(%i3) x@@version; 157(%o3) 5.36.1 158@end group 159@group 160(%i4) x@@timestamp; 161(%o4) 2015-06-02 11:26:48 162@end group 163@group 164(%i5) x@@host; 165(%o5) x86_64-unknown-linux-gnu 166@end group 167@group 168(%i6) x@@lisp_name; 169(%o6) GNU Common Lisp (GCL) 170@end group 171@group 172(%i7) x@@lisp_version; 173(%o7) GCL 2.6.12 174@end group 175@group 176(%i8) x; 177(%o8) 178Maxima version: "5.36.1" 179Maxima build date: "2015-06-02 11:26:48" 180Host type: "x86_64-unknown-linux-gnu" 181Lisp implementation type: "GNU Common Lisp (GCL)" 182Lisp implementation version: "GCL 2.6.12" 183@end group 184@end example 185 186The Maxima version string can (here 5.36.1) can look very different: 187 188@example 189(%i1) build_info(); 190(%o1) 191Maxima version: "branch_5_37_base_331_g8322940_dirty" 192Maxima build date: "2016-01-01 15:37:35" 193Host type: "x86_64-unknown-linux-gnu" 194Lisp implementation type: "CLISP" 195Lisp implementation version: "2.49 (2010-07-07) (built 3605577779) (memory 3660647857)" 196@end example 197 198@c The version number comes from "git describe", and is (in that example) 199@c 331 commits after the latest tag, that is reachable from that commit 200@c don't know how to describe it better... 201In that case, Maxima was not build from a released sourcecode, 202but directly from the GIT-checkout of the sourcecode. 203In the example, the checkout is 331 commits after the latest GIT tag 204(usually a Maxima (major) release (5.37 in our example)) and the 205abbreviated commit hash of the last commit was "8322940". 206 207Front-ends for maxima can add information about currently being used 208by setting the variables @code{maxima_frontend} and 209@code{maxima_frontend_version} accordingly. 210 211@opencatbox 212@category{Debugging} 213@closecatbox 214@end deffn 215 216