70896a91 |
1 | \section{Implementation Specification} |
ea4c19a4 |
2 | |
d65ad4d7 |
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 | |
ea78fc91 |
14 | Program configuration is encapsulated into the class \verb|configuration_manager|, |
d65ad4d7 |
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 |
ea78fc91 |
22 | open files as determined by the configuration (command line option or configuration file).\\ |
d65ad4d7 |
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 |
ea78fc91 |
28 | pointers to instances of \verb|tape_block|.\\ |
d65ad4d7 |
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 |
ea78fc91 |
34 | of each object must be one of the types which mark the end of an object.\\ |
d65ad4d7 |
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. |
ea4c19a4 |
40 | |
ea78fc91 |
41 | \subsubsection{Block factory} |
42 | The software makes use of C++ virtual methods allowing for convenient processing of |
d65ad4d7 |
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} |
ea4c19a4 |
71 | \subsubsection{Build environment} |
72 | The program has been successfully built under Linux with the following |
73 | programs: |
74 | \begin{itemize} |
d65ad4d7 |
75 | \item GNU GCC, version 4.1.2 |
76 | \item GNU make, version 3.81 |
77 | \item Doxygen, version 1.4.2 |
ea4c19a4 |
78 | \item Debian teTex package, version 3.0 |
d65ad4d7 |
79 | \item Graphviz dot tool, version 2.8 |
ea4c19a4 |
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. |
ea4c19a4 |
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} |
d65ad4d7 |
117 | |
118 | % End of the show.... |