| 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.... |