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 @end table
  43
  44 For example @code{run_testsuite(display_known_bugs = true, tests=[rtest5])}
  45 runs just test @code{rtest5} and displays the test that are marked as
  46 known bugs.
  47
  48 @code{run_testsuite(display_all = true, tests=["rtest1", rtest1a])} will
  49 run tests @code{rtest1} and @code{rtest2}, and displays each test.
  50
  51 @code{run_testsuite} changes the Maxima environment.
  52 Typically a test script executes @mref{kill} to establish a known environment
  53 (namely one without user-defined functions and variables)
  54 and then defines functions and variables appropriate to the test.
  55
  56 @code{run_testsuite} returns @code{done}.
  57
  58 @opencatbox{Categories:}
  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
  69 the tests to run.  If some of the tests in a file are known to fail,
  70 then instead of listing the name of the file, a list containing the
  71 file name and the test numbers that fail is used.
  72
  73 For example, this is a part of the default set of tests:
  74
  75 @example
  76  ["rtest13s", ["rtest14", 57, 63]]
  77 @end example
  78
  79 This specifies the testsuite consists of the files "rtest13s" and
  80 "rtest14", but "rtest14" contains two tests that are known to fail: 57
  81 and 63.
  82
  83 @opencatbox{Categories:}
  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}
  92 directory that is run as a part of the test suite by
  93 @mrefdot{run_testsuite}.
  94
  95 @opencatbox{Categories:}
  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 @ifinfo
 105 @fnindex Bugs
 106 @end ifinfo
 107
 108 Prints out Maxima and Lisp version numbers, and gives a link
 109 to the Maxima project bug report web page.
 110 The version information is the same as reported by @mrefdot{build_info}
 111
 112 When a bug is reported, it is helpful to copy the Maxima
 113 and Lisp version information into the bug report.
 114
 115 @code{bug_report} returns an empty string @code{""}.
 116
 117 @opencatbox{Categories:}
 118 @category{Debugging}
 119 @closecatbox
 120 @end deffn
 121
 122 @c -----------------------------------------------------------------------------
 123 @anchor{build_info}
 124 @deffn {Function} build_info ()
 125
 126 Returns a summary of the parameters of the Maxima build,
 127 as a Maxima structure (defined by @code{defstruct}).
 128 The fields of the structure are:
 129 @code{version}, @code{timestamp}, @code{host}, @code{lisp_name}, and @code{lisp_version}.
 130 When the pretty-printer is enabled (via @mref{display2d}),
 131 the structure is displayed as a short table.
 132
 133 See also @mrefdot{bug_report}
 134
 135 Examples:
 136
 137 @c ===beg===
 138 @c build_info ();
 139 @c x : build_info ()$
 140 @c x@version;
 141 @c x@timestamp;
 142 @c x@host;
 143 @c x@lisp_name;
 144 @c x@lisp_version;
 145 @c x;
 146 @c ===end===
 147 @example
 148 @group
 149 (%i1) build_info ();
 150 (%o1)
 151 Maxima version: "5.36.1"
 152 Maxima build date: "2015-06-02 11:26:48"
 153 Host type: "x86_64-unknown-linux-gnu"
 154 Lisp implementation type: "GNU Common Lisp (GCL)"
 155 Lisp implementation version: "GCL 2.6.12"
 156 @end group
 157 (%i2) x : build_info ()$
 158 @group
 159 (%i3) x@@version;
 160 (%o3)                               5.36.1
 161 @end group
 162 @group
 163 (%i4) x@@timestamp;
 164 (%o4)                         2015-06-02 11:26:48
 165 @end group
 166 @group
 167 (%i5) x@@host;
 168 (%o5)                      x86_64-unknown-linux-gnu
 169 @end group
 170 @group
 171 (%i6) x@@lisp_name;
 172 (%o6)                        GNU Common Lisp (GCL)
 173 @end group
 174 @group
 175 (%i7) x@@lisp_version;
 176 (%o7)                             GCL 2.6.12
 177 @end group
 178 @group
 179 (%i8) x;
 180 (%o8)
 181 Maxima version: "5.36.1"
 182 Maxima build date: "2015-06-02 11:26:48"
 183 Host type: "x86_64-unknown-linux-gnu"
 184 Lisp implementation type: "GNU Common Lisp (GCL)"
 185 Lisp implementation version: "GCL 2.6.12"
 186 @end group
 187 @end example
 188
 189 The Maxima version string can (here 5.36.1) can look very different:
 190
 191 @example
 192 (%i1) build_info();
 193 (%o1)
 194 Maxima version: "branch_5_37_base_331_g8322940_dirty"
 195 Maxima build date: "2016-01-01 15:37:35"
 196 Host type: "x86_64-unknown-linux-gnu"
 197 Lisp implementation type: "CLISP"
 198 Lisp implementation version: "2.49 (2010-07-07) (built 3605577779) (memory 3660647857)"
 199 @end example
 200
 201 @c The version number comes from "git describe", and is (in that example)
 202 @c 331 commits after the latest tag, that is reachable from that commit
 203 @c don't know how to describe it better...
 204 In that case, Maxima was not build from a released sourcecode,
 205 but directly from the GIT-checkout of the sourcecode.
 206 In the example, the checkout is 331 commits after the latest GIT tag
 207 (usually a Maxima (major) release (5.37 in our example)) and the
 208 abbreviated commit hash of the last commit was "8322940".
 209
 210 Front-ends for maxima can add information about currently being used
 211 by setting the variables @code{maxima_frontend} and
 212 @code{maxima_frontend_version} accordingly.
 213
 214 @opencatbox{Categories:}
 215 @category{Debugging}
 216 @closecatbox
 217 @end deffn
 218