@c -----------------------------------------------------------------------------
@c File        : Bugs.de.texi
@c License     : GNU General Public License (GPL)
@c Language    : German
@c Original    : Bugs.texi revision 1.15
@c Translation : Dr. Dieter Kaiser
@c Date        : 15.10.2010
@c Revision    : 16.03.2011
@c 
@c This file is part of Maxima -- GPL CAS based on DOE-MACSYMA
@c -----------------------------------------------------------------------------

@menu
* Einf@"uhrung in Programmfehler::
* Funktionen und Variablen f@"ur Programmfehler::
@end menu

@c -----------------------------------------------------------------------------
@node Einf@"uhrung in Programmfehler, Funktionen und Variablen f@"ur Programmfehler, Programmfehler, Programmfehler
@section Einf@"uhrung in Programmfehler
@c -----------------------------------------------------------------------------

Maxima wird st@"andig weiterentwickelt.  Der Funktionsumfang wird erweitert und 
Fehler, die bei einem Programm dieser Komplexit@"at kaum zu vermeiden sind, 
werden korrigiert.  Fehler k@"onnen berichtet werden.  Werden ausreichend
Informationen mitgeteilt, k@"onnen die Entwickler Maxima weiter verbessern.
Ein aktueller Link zur Webseite zum Berichten von Fehlern sowie die notwendigen 
Informationen @"uber die Maxima-Installation werden mit der Funktion 
@mref{bug_report} angezeigt.  Um die Installation auf dem Rechner zu testen, 
kann die Maxima-Testsuite mit der Funktion @mref{run_testsuite} ausgef@"uhrt 
werden.  Die folgende @"Ubersicht zeigt die Funktionen und Variablen f@"ur das 
Testen der Installation und das Berichten von Fehlern:

@verbatim
   run_testsuite     testsuite_files     bug_report     build_info
@end verbatim

@c -----------------------------------------------------------------------------
@node Funktionen und Variablen f@"ur Programmfehler, , Einf@"uhrung in Programmfehler, Programmfehler
@section Funktionen und Variablen f@"ur Programmfehler
@c -----------------------------------------------------------------------------

@c --- 15.10.2010 DK -----------------------------------------------------------
@anchor{run_testsuite}
@deffn {Funktion} run_testsuite ([@var{options}])

Die Funktion @code{run_testsuite} f@"uhrt die Maxima-Testsuite aus.  
Erfolgreiche Tests und Tests, die zwar nicht erfolgreich, aber als ein bekannter
Fehler gekennzeichnet sind, geben die Meldung "passed".  @code{run_testsuite} 
akzeptiert die folgenden optionalen Schl@"usselworte als Argumente:

@table @code
@item display_all
Hat das Schl@"usselwort @code{display_all} den Wert @code{true}, werden alle 
Tests angezeigt.  Der Standardwert ist @code{false}.  In diesem Fall werden nur 
die Tests angezeigt, die fehlschlagen.

@item display_known_bugs
Hat das Schl@"usselwort @code{display_known_bugs} den Wert @code{true}, werden 
alle Tests angezeigt, die als fehlerhaft gekennzeichnet sind.  Der Standardwert 
ist @code{false}.

@item tests
Das Schl@"usselwort @code{tests} erh@"alt eine Liste mit den Testdateien, die 
ausgef@"uhrt werden sollen.  Eine Testdatei kann durch eine Zeichenkette oder 
ein Symbol angegeben werden.  Der Standard ist, dass alle Testdateien 
ausgef@"uhrt werden, die in der Optionsvariablen @mref{testsuite_files}@w{} 
enthalten sind.

@item time
Hat das Schl@"usselwort @code{time} den Wert @code{true}, werden die Laufzeiten 
der einzelnen Testdateien angezeigt.  Hat @code{time} den Wert @code{all} und
@code{display_all} den Wert @code{true}, wird die Laufzeit jedes einzelnen 
Tests angezeigt.  Der Standardwert ist @code{false}.
@end table

Das Ausf@"uhren einer Testdatei kann die Maxima-Umgebung @"andern.
Typischerweise f@"uhrt eine Testdatei zuerst das Kommando @code{kill(all)} aus, 
um eine definierte Umgebung herzustellen, in der keine nutzerdefinierten 
Funktionen und Variablen vorhanden sind.  Siehe auch die Funktion @mrefdot{kill}

Testdateien k@"onnen auch von der Funktion @mref{batch} mit der Option
@code{test} ausgef@"uhrt werden.  Siehe die Dokumentation der Funktion
@code{batch} auch f@"ur ein Beispiel, wie eine Testdatei aufgebaut ist.

@code{run_testsuite} hat den R@"uckgabewert @code{done}.

Beispiele:

@example
(%i1) run_testsuite(tests = ["rtest1", rtest2]);
Running tests in rtest1: 111/111 tests passed
Running tests in rtest2: 66/66 tests passed

No unexpected errors found out of 177 tests.
Evaluation took:
  0.344 seconds of real time
  0.30402 seconds of total run time (0.30002 user, 0.00400 system)
  88.37% CPU
  581,206,031 processor cycles
  7,824,088 bytes consed
  
(%o1)                         done
@end example

Es werden zus@"atzlich alle Tests angezeigt.  Die Ausgabe wird hier nach dem
zweiten Test abgek@"urzt.

@example
(%i2) run_testsuite(display_all=true, tests=["rtest1",rtest2]);
Running tests in rtest1: 
********************** Problem 1 ***************
Input:
(fmakunbound(f), kill(functions, values, arrays))

Result:
done

... Which was correct.

********************** Problem 2 ***************
Input:
             2
f(x) := y + x

Result:
             2
f(x) := y + x

... Which was correct.

[...]
@end example

Im folgenden Beispiel werden die Tests ausgegeben, von denen bekannt ist, dass
sie fehlerhaft sind.  Dies sind die Tests mit den Nummern 76 und 78.

@example
(%i1) run_testsuite(display_known_bugs=true, tests=[rtest12]);
Running tests in rtest12:
@group
********************** Problem 76 ***************
Input:
           2
letsimp(foo (x))

Result:
       2
1 - bar (aa)

This differed from the expected result:
       2
1 - bar (x)
@end group
********************** Problem 78 ***************
Input:
           4
letsimp(foo (x))

Result:
   4            2
bar (aa) - 2 bar (aa) + 1

This differed from the expected result:
         2         4
1 - 2 bar (x) + bar (x)

76/78 tests passed

The following 2 problems failed: (76 78)

Error summary:
Errors found in /usr/local/share/maxima/5.23post/tests/rtest12.mac,
problems: (76 78)
2 tests failed out of 78 total tests.
Evaluation took:
  0.157 seconds of real time
  0.12801 seconds of total run time (0.12401 user, 0.00400 system)
  [Run times consist of 0.008 seconds GC time, 
   and 0.121 seconds non-GC time.]
  81.53% CPU
  9 forms interpreted
  71 lambdas converted
  254,604,658 processor cycles
  6,145,064 bytes consed
  
(%o0)                         done
@end example
@end deffn

@c --- 15.10.2010 DK -----------------------------------------------------------
@anchor{testsuite_files}
@defvr {Optionsvariable} testsuite_files

Die Optionsvariable @code{testsuite_files} enth@"alt die Liste der Testdateien, 
die von @mref{run_testsuite} standardm@"a@ss{}ig ausgef@"uhrt werden.  Wenn 
bekannt ist, dass einzelne Tests einer Testdatei fehlschlagen werden, dann wird 
anstatt dem Namen der Datei eine Liste eingef@"ugt, die den Namen und die 
Nummern der fehlerhaften Tests enth@"alt.  Das folgende Beispiel zeigt die
Zuweisung einer neuen Liste und wie fehlerhafte Tests gekennzeichnet werden:

@example
 testsuite_files : ["rtest13s", ["rtest14", 57, 63]]
@end example

Die Eintr@"age der Liste bedeuten, dass die Dateien "rtest13s" und "rtest14" von
der Funktion @code{run_testsuite} ausgef@"uhrt werden sollen und das bekannt
ist, dass die Tests mit den Nummern 57 und 63 der Testdatei "rtest14"
fehlschlagen werden.
@end defvr

@c --- 15.10.2010 DK -----------------------------------------------------------
@anchor{bug_report}
@deffn {Funktion} bug_report ()

Zeigt die Maxima- und Lisp-Version der Installation sowie einen Link zur
Webseite des Maxima-Projekts.  Die Informationen zur Version werden auch von
@mref{build_info} angezeigt.  Wenn ein Programmfehler berichtet wird, ist es
hilfreich, die Maxima- und Lisp-Version in den Fehlerbericht aufzunehmen.
@code{bug_report} gibt eine leere Zeichenkette @code{""} zur@"uck.

Beispiel:

@example
(%i1) bug_report();

Please report bugs to:
    https://sourceforge.net/p/maxima/bugs/
To report a bug, you must have a Sourceforge account.
Please include the following information with your bug report:
-------------------------------------------------------------
Maxima version: "5.36.1"
Maxima build date: "2015-06-02 11:26:48"
Host type: "x86_64-unknown-linux-gnu"
Lisp implementation type: "GNU Common Lisp (GCL)"
Lisp implementation version: "GCL 2.6.12"
-------------------------------------------------------------
The above information is also reported by the function 'build_info()'.
@end example
@end deffn

@c --- 15.10.2010 DK -----------------------------------------------------------
@anchor{build_info}
@deffn {Funktion} build_info ()

Zeigt die Maxima- und Lisp-Version der Installation.  @code{build_info} gibt die Eigenschaften der Maxima-Version als Maxima structure (definiert durch @code{defstruct}) zur@"uck.
Die Felder der Struktur sind:
@code{version}, @code{timestamp}, @code{host}, @code{lisp_name} und @code{lisp_version}.
Wenn die Ausgabe formatiert erfolgt (mit @code{display2d:true;}),
werden die Ergebnisse als kurze Tabelle ausgegeben.

Beispiel:

@example
@group
(%i1) build_info ();
(%o1) 
Maxima version: "5.36.1"
Maxima build date: "2015-06-02 11:26:48"
Host type: "x86_64-unknown-linux-gnu"
Lisp implementation type: "GNU Common Lisp (GCL)"
Lisp implementation version: "GCL 2.6.12"
@end group
(%i2) x : build_info ()$
@group
(%i3) x@@version;
(%o3)                               5.36.1
@end group
@group
(%i4) x@@timestamp;
(%o4)                         2015-06-02 11:26:48
@end group
@group
(%i5) x@@host;
(%o5)                      x86_64-unknown-linux-gnu
@end group
@group
(%i6) x@@lisp_name;
(%o6)                        GNU Common Lisp (GCL)
@end group
@group
(%i7) x@@lisp_version;
(%o7)                             GCL 2.6.12
@end group
@group
(%i8) x;
(%o8) 
Maxima version: "5.36.1"
Maxima build date: "2015-06-02 11:26:48"
Host type: "x86_64-unknown-linux-gnu"
Lisp implementation type: "GNU Common Lisp (GCL)"
Lisp implementation version: "GCL 2.6.12"
@end group
@end example

Der Versionsstring (hier 5.36.1) kann auch folgendermassen aussehen:
branch_5_37_base_331_g8322940_dirty

@example
(%i1) build_info();
(%o1) 
Maxima version: "branch_5_37_base_331_g8322940_dirty"
Maxima build date: "2016-01-01 15:37:35"
Host type: "x86_64-unknown-linux-gnu"
Lisp implementation type: "CLISP"
Lisp implementation version: "2.49 (2010-07-07) (built 3605577779) 
     (memory 3660647857)"
@end example

@c The version number comes from "git describe", and is (in that example)
@c 331 commits after the latest tag, that is reachable from that commit
@c dont know how to describe it better...
In diesem Fall wurde Maxima nicht von einem Release sondern direkt aus dem Git checkout des
Sourcecodes compiliert.
Im obigen Beispiel ist der Checkout 331 Commits nach dem letzten Git-Tag (@"ublicherweise ein
Maxima-Release (5.37 im obigen Beispiel)) und der verk@"urzte Commit Hash des letzten Commits
lautet "8322940".
@end deffn

@c --- End of file Bugs.de.texi ------------------------------------------------

