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