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