GDB support draft

gdb/.gdbinit

@@ -1,3 +1,7 @@
 define pp
   p (char*) Bstringval ((void*) $arg0)    
 end    
+
+define pc
+  p (char*) Bstringval ((void*) ((*(int**)($ebp-4)) [$arg0]))
+end

spec/05.driver_options.tex

@@ -41,6 +41,7 @@ Additionally, the following options can be given to the driver:
   basename as the source one, with the extension replaced with "\texttt{.html}".
 \item "\texttt{-ds}"~--- forces the driver to sump stack machine code. The option is only in effect in stack interpreter on
   native mode. The dump is written in the file "\texttt{.sm}".
+\item "\texttt{-g}"~--- compile with debug information (see Section~\ref{sec:debugging}).
 \item "\texttt{-v}"~--- makes the driver to print the version of the compiler.
 \item "\texttt{-h}"~--- makes the driver to print the help on the options.
 \end{itemize}

spec/06.debugging.tex

@@ -0,0 +1,36 @@
+\chapter{Debugging Support}
+\label{sec:debugging}
+
+Current implementation supports a minimalistic debugging with \textsc{GDB}~\cite{gdb}. In order to include the debug information into object files/executable these files
+have to be compiled with the command-line option "\texttt{-g}" (see Section~\ref{sec:driver}).
+
+The following debugging features are supported:
+
+\begin{itemize}
+\item setting breakpoints on lines; note, the line number information is generated only for identifiers, so, if a line does not contain even a single identifier, it
+  will not be visible for the debugger;
+\item setting breakpoints on functions:
+  \begin{itemize}
+    \item by source name for top-level function;
+    \item by internal name for nested functions or lambdas; an internal name can be found in stack machine program dump (option "\texttt{-ds}", see Section~\ref{sec:driver});
+  \end{itemize}
+\item stepping over/into;
+\item inspecting the values of global variables by their source names;
+\item inspecting the values of function arguments and local variables (include those in nested scopes) by their source names;
+\item inspecting the values in closures by their indices; the indices for closure elements can be found in stack machine
+  program dump (option "\texttt{-ds}", see Section~\ref{sec:driver}).
+\end{itemize}
+
+In addition a number of customized debugging command definitions is provided to make the debugging easier. These definitions reside in the "\texttt{gdb/.gdbinit}"
+file of the distribution; to make effect either the whole file has to be put in a proper place (usually the root of the home directory), or its content has to be
+imported into an existing \textsc{GDB} profile; consult \textsc{GDB} documentation for details.
+
+The following customized commands are available:
+
+\begin{itemize}
+\item "\texttt{pp }$e$", where "$e$" is a \textsc{GDB} expression. The commands prints in a human-readable form the value of the expression. For example,
+  "\texttt{pp x}" prints a value of a variable/parameter "\texttt{x}".
+\item "\texttt{pc }$i$", where "$i$" is an integer number. The commands prints a value of $i$-component of current closure.
+\end{itemize}
+
+

spec/lama-spec.bib

@@ -1,3 +1,4 @@
+
 @book{A68,
 author = {Wijngaarden, A. van},
 title = {Report on the Algorithmic Language ALGOL 68},
@@ -12,6 +13,12 @@ publisher = {Printing by the Mathematisch Centrum}
   url     =    "https://www.ocaml.org"
 }
 
+@manual{gdb,
+  title =        "{Debugging with GDB}",
+  bibdate =      "September 10, 2020",
+  url     =    "https://sourceware.org/gdb/current/onlinedocs/gdb/"
+}
+
 @manual{Haskell,
   title =        "{Haskell Language}",
   bibdate =      "February 17, 2020",

spec/lama-spec.tex

@@ -199,7 +199,8 @@ language=lama
 \input{03.concrete_syntax}
 \input{04.extensions}
 \input{05.driver_options}
-\input{06.standard_library}
+\input{06.debugging}
+\input{07.standard_library}
 
 \bibliographystyle{plainurl}
 \bibliography{lama-spec}