-recoveredHEADmaster

3 files changed, 112 insertions, 0 deletions

diff --git a/doc/man/man1/pathologist.1 b/doc/man/man1/pathologist.1
new file mode 100644
index 0000000..1fceff8
--- /dev/null
+++ b/doc/man/man1/pathologist.1
@@ -0,0 +1,21 @@
+.TH pathologist 1 2013-03-01 "Monkey Debugging System" "Version 0.1"
+
+.SH NAME
+pathologist \- Automatically generates bug reports.
+
+.SH SYNOPSIS
+.B pathologist -d FILE [ options ] [ -- ] BINARY
+.br
+.B pathologist -h | -v
+
+.SH DESCRIPTION
+With pathologist you can run an application and automatically generate a
+bug report, if the programm crashes. Before you can use pathologist, 
+you first have to generate an expression database with seaspider. For more
+information about how to use pathologist as part of the Monkey Debugging
+System see
+.B monkey(7)
+.\.
+
+
+.SH OPTIONS
diff --git a/doc/man/man1/seaspider.1 b/doc/man/man1/seaspider.1
new file mode 100644
index 0000000..e247883
--- /dev/null
+++ b/doc/man/man1/seaspider.1
@@ -0,0 +1,15 @@
+.TH seaspider 1 2013-03-01 "Monkey Debugging System" "Version 0.1"
+
+.SH NAME
+seaspider \- builds an expression database via static code analysis.
+
+.SH SYNOPSIS
+
+.SH DESCRIPTION
+For more information about how to use the generated database with pathologist
+as part of the Monkey Debugging System see
+.B monkey(7)
+.\.
+
+
+.SH OPTIONS
diff --git a/doc/man/man7/monkey.7 b/doc/man/man7/monkey.7
new file mode 100644
index 0000000..9087f8a
--- /dev/null
+++ b/doc/man/man7/monkey.7
@@ -0,0 +1,76 @@
+.TH monkey 7 2013-03-01 "Monkey Debugging System" "Version 0.1"
+
+.SH NAME
+monkey \- An automated debugging tool.
+
+.SH DESCRIPTION
+.P
+The Monkey Debugging System is a three part toolset for automtically generating
+bug reports from program crashes.
+.P
+To allow automated crash analysis with pathologist, you first have to generate
+an expression database with
+.B seaspider(1)
+. Seaspider will do some static code analysis and generate a sqlite database
+file containing all the expressions in your source code.  If you have
+some variables in your source code which contain private information
+of the user that must not be included in bug reports, you can specify
+an ignore file which contains regular expressions to exclude those
+variables from the database, and therefore prevent later appearance of
+the private data in the bug report.
+
+.P
+After the expression database has been generated, you can ship this database
+together with your application.  On the target system, the user can then use
+.B pathologist(1)
+, to run your application under supervision using 
+.B gdb(1)
+.  If the application crashes,
+a post-mortem analysis will be performed. The stack will be analyzed and all relevant
+expressions in the stacktrace and other information about the crash will be evaluated and written to a bug report
+in XML format. When the report has been succesfully written, Pathologist can
+send the report to the developer via mail.
+
+.P
+The third component of the monkey debugging system is the
+.B entomologist(1)
+, which is not yet functional.  The Entomologist but will provide comparison and clustering algorithms
+for the generated reports.
+
+.SH REQUIREMENTS
+.P
+To use the Monkey Debugging System, you have to fulfill the following
+requirements.
+
+.P
+Your project has to be written in C (C++ support is missing in Seaspider).
+
+.P
+To use Seaspider, your project has to be built with GNU Autotools. Other Build
+Systems are not supported, but it should still be possible to use them as well,
+if you can set the compiler and compiler options yourself.
+
+.P
+You need gdb in version 7 or later, and we have only tested the system on GNU/Linux.
+
+.SH LIMITATIONS
+.P
+Pathologist can only (nicely) handle the following signals at this time: SIGSEGV (Segfault),
+SIGABRT (Assertion), SIGBUS (Bad Memory Access), and SIGFPE (Arithmetic Exception).
+
+.P
+Your C source file names have to be globally unique in your project.
+
+.P
+Due to gdb changing the respective values on the stack while evaluating,
+increments and decrements are problematic if contained in the line of code,
+which causes the crash. Seaspider will just remove every single increment and
+decrement operator before writing expressions to the database, so if your
+program crashes on a line
+.B a = b[++c];
+, the report will only contain the
+value of
+.B b[c]
+.
+
+