*** empty log message ***

[h316.git] / pc-tools / ldc2 / doc / impl_spec.tex

\section{Implementation Specification}

\subsection{Theory of operation}
\subsubsection{Overview}

The program is implemented using standard C++.

While the data structures according to \cite{ser16:progref}
are designed consequently object oriented,
most of the actual processing of the data after reading in is done 
by the routines contained in
\verb|main.cpp|, \verb|config.cpp| and \verb|tool.cpp|.

Program configuration is capsuled into the class \verb|configuration_manager|,
used by the routines in \verb|config.cpp|.

\subsubsection{Program flow}
The \verb|main()| routine sets up the working environment using the \verb|do_config()|
subroutine contained in \verb|config.cpp|. This contains parsing the command line,
reading a configuration file, and setting the global \verb|cfg_*| flags. The input and
output file descriptors \verb|in_fd| and \verb|out_fd| are assigned to 0 and 1 respective
files as stated in the configuration (command line option or configuration file).
The \verb|configuration_manager| is able to dynamically generate help output for all
options.

The next call is \verb|read_tape()|, the data input routine. In \verb|read_tape()|,
the static factory method \verb|tape_block::gen_from_fd()| is used to create and
check blocks, taking data directly from the global file descriptor \verb|in_fd|.\\
At the end of \verb|read_tape()|, the vector \verb|tape| has been filled with
pointers to instances of \verb|tape_block|.

In the next step, the routine \verb|process_tape()| is called, in which
integrity checks on object level and splitting to files (if desired)
are accomplished. Every valid and complete object consist of either one
single \verb|eot_block| or a series of \verb|data_block|s, while the last block
of each object must be one of the types which mark the end of an object.

After all that, \verb|process_symbols()| is called. This routine generates three vectors
containing symbol names: \verb|exported|, \verb|called|, and \verb|unsatisfied|.
The latter is the difference of \verb|called| and \verb|exported|.\\
If desired, those vectors are written out to \verb|out_fd|, one symbol per line.

\subsubsection{Block factory}
The software makes use of C++ virtual methods allowing for convinient processing of
multiple kinds of blocks without knowing much about the block type currently worked 
on.\\
The block factory consists of the static factory method \verb|tape_block::gen_from_fd()| 
and a corresponding private constructor of class \verb|tape_block|. The constructor 
creates a block and reads data from the given file descriptor. The factory method 
then tries to determine the block's type and recreate an object of the most accurate
subtype applying to the block. Information about the block types is contained in 
the block data itself.  A pointer to the newly created object is returned or one 
of the exception defined in class \verb|tape_block| is thrown.


\subsection{Detailed documentation}
\subsubsection{Doxygen}
The source code has been documented using  Doxygen and appropriate
comments throughout the program code. Doxygen generates a very useful
html documentation containing very usable diagrams (not strictly UML, but
very fine anyway), lists and detailed documentation.

The Doxygen configuration also creates man pages, latex sources with
makefile for PostScript and PDF output.

\subsubsection{Not in this document}
I have decided not to create UML class and collaboration diagrams because
in my opinion the Doxygen documentation perfectly covers those needs.

The project already took several times the time I allocated in my schedule....

\subsection{Building \pname}
\subsubsection{Build environment}
The program has been successfully built under Linux with the following
programs:
\begin{itemize}
\item GNU GCC, version 4.1.2
\item GNU make, version 3.81
\item Doxygen, version 1.4.2
\item Debian teTex package, version 3.0
\item Graphviz dot tool, version 2.8
\end{itemize}
At least the the software (without docs) should be compile on any 
POSIX compatible system with a fairly recent GCC and GNU make 
installed.

\subsubsection{Build instructions}
There is a simple \verb|Makefile| which eases the standard build
process for the application and documentation. Changes may be
necessary to compile on a system other than stated in the last 
paragraph.

To build the application, follow these easy steps:
\begin{itemize}

\item Change directory to the \pname direcory.\\
(Hint: That is the directory containing the subdirs \verb|src| 
and \verb|doc|.)

\item Run \emph{make} (or \emph{gmake}).

\item If you like, put the resulting  binary somewhere in your system.
\end{itemize}


Further useful targets in the \verb|Makefile|:
\begin{itemize}

\item \verb|doc|: Build the Latex documentation (this document) in the
\verb|doc| subfolder.

\item \verb|doxy|: Build Doxygen source code documentation.\\
The Doxygen output is placed in the subdir \verb|doxy|.

\item \verb|clean|: Delete all files generated by the make process,
including binaries and documentation.

\end{itemize}

%  End of the show....