pc-tools/ldc2/doc/impl_spec.tex

   1 \section{Implementation Specification}
   2
   3 \subsection{Theory of operation}
   4 \subsubsection{Overview}
   5
   6 The program is implemented using standard C++.
   7
   8 While the data structures according to \cite{ser16:progref}
   9 are designed consequently object oriented,
  10 most of the actual processing of the data after reading in is done
  11 by the routines contained in
  12 \verb|main.cpp|, \verb|config.cpp| and \verb|tool.cpp|.
  13
  14 Program configuration is capsuled into the class \verb|configuration_manager|,
  15 used by the routines in \verb|config.cpp|.
  16
  17 \subsubsection{Program flow}
  18 The \verb|main()| routine sets up the working environment using the \verb|do_config()|
  19 subroutine contained in \verb|config.cpp|. This contains parsing the command line,
  20 reading a configuration file, and setting the global \verb|cfg_*| flags. The input and
  21 output file descriptors \verb|in_fd| and \verb|out_fd| are assigned to 0 and 1 respective
  22 files as stated in the configuration (command line option or configuration file).
  23 The \verb|configuration_manager| is able to dynamically generate help output for all
  24 options.
  25
  26 The next call is \verb|read_tape()|, the data input routine. In \verb|read_tape()|,
  27 the static factory method \verb|tape_block::gen_from_fd()| is used to create and
  28 check blocks, taking data directly from the global file descriptor \verb|in_fd|.\\
  29 At the end of \verb|read_tape()|, the vector \verb|tape| has been filled with
  30 pointers to instances of \verb|tape_block|.
  31
  32 In the next step, the routine \verb|process_tape()| is called, in which
  33 integrity checks on object level and splitting to files (if desired)
  34 are accomplished. Every valid and complete object consist of either one
  35 single \verb|eot_block| or a series of \verb|data_block|s, while the last block
  36 of each object must be one of the types which mark the end of an object.
  37
  38 After all that, \verb|process_symbols()| is called. This routine generates three vectors
  39 containing symbol names: \verb|exported|, \verb|called|, and \verb|unsatisfied|.
  40 The latter is the difference of \verb|called| and \verb|exported|.\\
  41 If desired, those vectors are written out to \verb|out_fd|, one symbol per line.
  42
  43 \subsubsection{Block factory}
  44 The software makes use of C++ virtual methods allowing for convinient processing of
  45 multiple kinds of blocks without knowing much about the block type currently worked
  46 on.\\
  47 The block factory consists of the static factory method \verb|tape_block::gen_from_fd()|
  48 and a corresponding private constructor of class \verb|tape_block|. The constructor
  49 creates a block and reads data from the given file descriptor. The factory method
  50 then tries to determine the block's type and recreate an object of the most accurate
  51 subtype applying to the block. Information about the block types is contained in
  52 the block data itself.  A pointer to the newly created object is returned or one
  53 of the exception defined in class \verb|tape_block| is thrown.
  54
  55
  56 \subsection{Detailed documentation}
  57 \subsubsection{Doxygen}
  58 The source code has been documented using  Doxygen and appropriate
  59 comments throughout the program code. Doxygen generates a very useful
  60 html documentation containing very usable diagrams (not strictly UML, but
  61 very fine anyway), lists and detailed documentation.
  62
  63 The Doxygen configuration also creates man pages, latex sources with
  64 makefile for PostScript and PDF output.
  65
  66 \subsubsection{Not in this document}
  67 I have decided not to create UML class and collaboration diagrams because
  68 in my opinion the Doxygen documentation perfectly covers those needs.
  69
  70 The project already took several times the time I allocated in my schedule....
  71
  72 \subsection{Building \pname}
  73 \subsubsection{Build environment}
  74 The program has been successfully built under Linux with the following
  75 programs:
  76 \begin{itemize}
  77 \item GNU GCC, version 4.1.2
  78 \item GNU make, version 3.81
  79 \item Doxygen, version 1.4.2
  80 \item Debian teTex package, version 3.0
  81 \item Graphviz dot tool, version 2.8
  82 \end{itemize}
  83 At least the the software (without docs) should be compile on any
  84 POSIX compatible system with a fairly recent GCC and GNU make
  85 installed.
  86
  87 \subsubsection{Build instructions}
  88 There is a simple \verb|Makefile| which eases the standard build
  89 process for the application and documentation. Changes may be
  90 necessary to compile on a system other than stated in the last
  91 paragraph.
  92
  93 To build the application, follow these easy steps:
  94 \begin{itemize}
  95
  96 \item Change directory to the \pname direcory.\\
  97 (Hint: That is the directory containing the subdirs \verb|src|
  98 and \verb|doc|.)
  99
 100 \item Run \emph{make} (or \emph{gmake}).
 101
 102 \item If you like, put the resulting  binary somewhere in your system.
 103 \end{itemize}
 104
 105
 106 Further useful targets in the \verb|Makefile|:
 107 \begin{itemize}
 108
 109 \item \verb|doc|: Build the Latex documentation (this document) in the
 110 \verb|doc| subfolder.
 111
 112 \item \verb|doxy|: Build Doxygen source code documentation.\\
 113 The Doxygen output is placed in the subdir \verb|doxy|.
 114
 115 \item \verb|clean|: Delete all files generated by the make process,
 116 including binaries and documentation.
 117
 118 \end{itemize}
 119
 120 %  End of the show....