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 @fnindex Bugs
 104 @deffn {Function} bug_report ()
 105
 106 Prints out Maxima and Lisp version numbers, and gives a link
 107 to the Maxima project bug report web page.
 108 The version information is the same as reported by @mrefdot{build_info}
 109
 110 When a bug is reported, it is helpful to copy the Maxima
 111 and Lisp version information into the bug report.
 112
 113 @code{bug_report} returns an empty string @code{""}.
 114
 115 @opencatbox{Categories:}
 116 @category{Debugging}
 117 @closecatbox
 118 @end deffn
 119
 120 @c -----------------------------------------------------------------------------
 121 @anchor{build_info}
 122 @deffn {Function} build_info ()
 123
 124 Returns a summary of the parameters of the Maxima build,
 125 as a Maxima structure (defined by @code{defstruct}).
 126 The fields of the structure are:
 127 @code{version}, @code{timestamp}, @code{host}, @code{lisp_name}, and @code{lisp_version}.
 128 When the pretty-printer is enabled (via @mref{display2d}),
 129 the structure is displayed as a short table.
 130
 131 See also @mrefdot{bug_report}
 132
 133 Examples:
 134
 135 @c ===beg===
 136 @c build_info ();
 137 @c x : build_info ()$
 138 @c x@version;
 139 @c x@timestamp;
 140 @c x@host;
 141 @c x@lisp_name;
 142 @c x@lisp_version;
 143 @c x;
 144 @c ===end===
 145 @example
 146 @group
 147 (%i1) build_info ();
 148 (%o1)
 149 Maxima version: "5.36.1"
 150 Maxima build date: "2015-06-02 11:26:48"
 151 Host type: "x86_64-unknown-linux-gnu"
 152 Lisp implementation type: "GNU Common Lisp (GCL)"
 153 Lisp implementation version: "GCL 2.6.12"
 154 @end group
 155 (%i2) x : build_info ()$
 156 @group
 157 (%i3) x@@version;
 158 (%o3)                               5.36.1
 159 @end group
 160 @group
 161 (%i4) x@@timestamp;
 162 (%o4)                         2015-06-02 11:26:48
 163 @end group
 164 @group
 165 (%i5) x@@host;
 166 (%o5)                      x86_64-unknown-linux-gnu
 167 @end group
 168 @group
 169 (%i6) x@@lisp_name;
 170 (%o6)                        GNU Common Lisp (GCL)
 171 @end group
 172 @group
 173 (%i7) x@@lisp_version;
 174 (%o7)                             GCL 2.6.12
 175 @end group
 176 @group
 177 (%i8) x;
 178 (%o8)
 179 Maxima version: "5.36.1"
 180 Maxima build date: "2015-06-02 11:26:48"
 181 Host type: "x86_64-unknown-linux-gnu"
 182 Lisp implementation type: "GNU Common Lisp (GCL)"
 183 Lisp implementation version: "GCL 2.6.12"
 184 @end group
 185 @end example
 186
 187 The Maxima version string (here 5.36.1) can look very different:
 188
 189 @example
 190 (%i1) build_info();
 191 (%o1)
 192 Maxima version: "branch_5_37_base_331_g8322940_dirty"
 193 Maxima build date: "2016-01-01 15:37:35"
 194 Host type: "x86_64-unknown-linux-gnu"
 195 Lisp implementation type: "CLISP"
 196 Lisp implementation version: "2.49 (2010-07-07) (built 3605577779) (memory 3660647857)"
 197 @end example
 198
 199 @c The version number comes from "git describe", and is (in that example)
 200 @c 331 commits after the latest tag, that is reachable from that commit
 201 @c don't know how to describe it better...
 202 In that case, Maxima was not build from a released sourcecode,
 203 but directly from the GIT-checkout of the sourcecode.
 204 In the example, the checkout is 331 commits after the latest GIT tag
 205 (usually a Maxima (major) release (5.37 in our example)) and the
 206 abbreviated commit hash of the last commit was "8322940".
 207
 208 Front-ends for maxima can add information about currently being used
 209 by setting the variables @code{maxima_frontend} and
 210 @code{maxima_frontend_version} accordingly.
 211
 212 @opencatbox{Categories:}
 213 @category{Debugging}
 214 @closecatbox
 215 @end deffn
 216