doc/info/Bugs.texi

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