3. Source Code Organization
Keywords: TechDoc

Next: 4. TCM User Interface Up: Toolkit for Conceptual Modeling Previous: 2. System Architecture
Subsections

- 3.1 Source code versus design criteria
- 3.2 Individual files and directories
- 3.3 Object libraries

#
3. Source Code Organization

# 3.1 Source code versus design criteria

Figure 3.1: Logical source code organization.

In this chapter we explain how the source code of TCM is organized. TCM basically consists of about two dozen graphical editors and a startup program. The source code can be found in the directory `$TCM_HOME/src`. The TCM source code is physically split over several subdirectories. The sources can be compiled into a number of object libraries and executables. The source code is split in order to factor out commonalities between the programs. See figure 3.1 for a Venn-diagram like overview of the commonalities of the source code. The entire TCM source is called Global, the sources of the programs that have an X/Motif GUI, are called GUI. The sources that are used in all editors, are called Editor. The sources that are used in all diagram editors, are called Diagram. The sources that are used in all table editors are called Table. The sources that are used in the editor TERD are called TERD etc. For instance, the editor TSSD uses the sources of the TSSD area, the TERD area, Diagram, Editor and Global, but it does not use Table or TCRD. See figure 3.2 for an overview of the current TCM development directory structure. The sources are physically split over several subdirectories of the src directory. This is done according to the following criteria:

- All code that is global and that is not part of the other areas is collected in the directory `src/gl`. This code is compiled into a library called `libglobal`. This includes common classes for lists, strings, Unix utilities etc. that can be used in any program, not necessarily a TCM tool.

- All code that comprises the graphical user interface but which is not specific for any TCM program is collected in the directory `src/ui`. This code is compiled into a library called `libgui`. This includes a generic application framework for Motif based C++ programs, classes for drawing lines and other shapes under X, classes for building all kinds of pop-up dialog windows, classes for making various pop-up and pull-down menus etc.

- All code that lies in the editor area (and in the TCM area) but not in one of the subareas, is collected in the directory `src/ed`. This code is compiled into a library called `libeditor` and in the executable `tcm`, the startup program. The libeditor library includes things that are applicable to all TCM editors such as saving and loading documents (the generic part of it), printing documents, the on-line help and it contains a number of abstract classes like Document, Viewer and Command on which specific editor classes are based.

- All code that lies in the diagram area and that is not part of one of the diagram subareas, is collected in directory `src/dg`. This code is compiled into a library called `libdiagram`. This includes classes for (abstract) graphs (and classes for nodes and edges), classes for graphical shapes (boxes, lines, ellipses) and classes for most diagram edit commands (CreateNodeCmd, CreateEdgeCmd, DeleteShapesCmd,...). This library is used by every specific diagram editor.

- All code that lies in the table area is collected in directory `src/tb`. This code is compiled into a library called `libtable`. This includes classes for (abstract) tables having rows and columns of cells and it includes all the table edit commands. This library is used by each table editor.

- All code that is specific one or more (but not all) of the diagram editors, is collected in the directory `src/sd` (specific diagram). Each specific diagram editor can be compiled into a distinct executable (at least in principle, it is also possible to compile more editors into one executable). As you can see in the picture, the code of some editors includes the code of others (e.g. TSSD code includes TERD specific code). The specific diagram editor code consists of C++ classes derived from (possibly abstract) classes in libdiagram or from other specific diagram editor classes. These classes are (indirectly) derived of the libdiagram classes Graph, DiagramWindow, DiagramChecks, DiagramViewer, Diagram, Shape, ShapeView, Node and Edge. The tool specific constraints are all implemented in the classes derived from Graph, DiagramChecks, Node and Edge. Because the specific diagram editor code is so diverse it is subdivided further into separate subdirectories:
  - `src/sd/bv` is for the behavior view editors (TSTD, TATD, TRPG, TPSD),
  - `src/sd/dv` is for the data view editors (TERD, TESD, TSSD, TCRD, TUCD),
  - `src/sd/fv` is for the function view editors (TDFD, TEFD, TSND),
  - `src/sd/pv` is for the physical view editors (TCPD, TDPD),
  - `src/sd/gd` is for TGD and
  - `src/sd/tr` is for the tree editors (TGTT, TFRT).
  The TGD sources form the most simple diagram editor and it can be used as a basis for developing your own diagram editors. Specific editors that reside in the same directory can share one or more classes (for instance, the class BinaryRelationship is used both by TSSD and TUCD), or, one editor shares/extends all classes of another editor (for instance, the classes of TFRT are all specializations of the classes of TGTT).

- All code that is specific for the different table editors, is collected in the directory `src/st`. The amount of specific table code is rather small. The specific code consists entirely of specializations of the following classes in libtable: TableWindow, TableViewer and Table. Also, most of the tool specific constraints are implemented in these specializations of class Table.

In principle each C++ class is declared in a distinct header file and has a distinct source file for the implementation. The files names are equal to the class name except that file names are in lower case letters by convention. Header files have suffix '.h' and source file have suffix '.c'. The reason that C++ source files have suffix '.c', which is originally used only for C programs, is that some C++ compilers require a suffix '.C', and some require '.cc' or '.cpp'. There is no C++ file name suffix that is accepted by all compilers that we have used except the '.c' suffix.

Figure 3.2: TCM directory tree.

#
3.2 Individual files and directories

In the previous section we described the contents of the `src` subdirectory. Here we will describe the individual files and directories that are included in the source code distributions of TCM. The TCM distribution top-level directory contains the following files:

- `CHANGELOG`, which contains the differences between the consecutive TCM versions.
- `COPYING`, which is the GNU public license.
- `FILEMAP`, which lists and describes the files and directories in the TCM executable distributions.
- `INSTALL`, which tells how to install the binary and source code distributions.
- `MANIFEST`, which lists all files and directories in the TCM distribution.
- `Makefile`, which is the top-level Makefile. Most sub(sub)directories contain a Makefile too. See chapter 7 for what to do with these Makefiles.
- `README`, which is the README file about the TCM project, the software, manuals, distributions etc.
- `tcm.lsm` is a file that describes TCM in the format that is required by the Linux software map. TCM is registered in the LSM (`http://www.execpc.com/lsm/`).
- `tcm-dynmotif-2.0.spec`. RPM spec file for building a TCM RPM distribution that links dynamically with the Motif/LessTif library. You can use (a modified copy of) this spec-file to build your own TCM RPMs. See `http://www.rpg.org` for more information about RPMs.
- `tcm-statmotif-2.0.spec`. RPM spec file for building a TCM RPM distribution that is statically linked with a Motif library.

The top-level directory contains the following directories:

- `bin/`. Here the TCM editors and other binaries are put after compilation. Also this directory contains a number of utility programs:
  - `bin/mkbindist`. This is a shell script that makes a tar.gz file of a binary distribution of the compiled source code. The script needs two arguments for the version number and the platform, e.g. `mkbindist 2.0 solaris.sparc`. This will create the file `tcm-2.0.bin.solaris.sparc.tar.gz` in `$TCM_HOME`. The files that will be included are listed in the code of the script itself.
  - `bin/mksrcdist`. This is a shell script that makes a tar.gz file of the source code. It needs one argument for the version number, e.g. `mksrcdist 2.0`. This will create the file `tcm-2.0.src.tar.gz` in `$TCM_HOME`. The files that will be included are listed in the code of the script itself.
  - `bin/mkclasslist`. This is a shell script that writes the names of all header files of the source code to standard output in alphabetical order.
  - `bin/psf`. This is a Perl script that is used to filter PostScript output (see `man psf`).

- `doc/`. Here all technical and user documentation can be found. The documentation is in HTML-format and possibly in PostScript and/or PDF format. The file `doc/index.html` links to all the different HTML documents. The documentation includes:

  - User's guide. In `usersguide/index.html` you can find an HTML version. A PostScript version can be found in `usersguide-2.0.ps.gz` (large PostScript files in TCM are always gzipped to save disk space). Optionally a PDF copy is put in `doc/usersguide-2.0.pdf`
  - Developer's guide, which is the document that you are reading now. In
    `developersguide/index.html` you can find an HTML version. A gzipped PostScript version can be found in `developersguide-2.0.ps.gz`. Optionally a PDF copy is found in `developersguide-2.0.pdf`
  - Source code documentation. For each C++ class an HTML page is generated by the program DOC++ (see chapter 5). The HTML index is in `sourcecode/index.html`. Also a PostScript document with all the source code documentation can be found in `sourcecode-2.0.ps.gz`
  - Specifications. The directory `specifications` contains a number of specifications (made with TCM) of some individual editors.
  - Wish lists. The directory `wishlist` contains:
    - `FutureDevelopments.html`. An overview of major TCM extensions that we have in mind.
    - `WishList.html`. A list with unfulfilled wishes for TCM.
    - `WishListDone.html`. A list with fulfilled wishes for TCM.
  - Document sources. In the directory `docsrc` you can find the LATEX, EPS and TCM files that comprise the sources of the documentation. These files are not included in the source code distribution itself. The sources can be downloaded separately from our FTP-site, from a file `tcm-2.0.docsrc.tar.gz` The sources contain a number of Makefiles to generate a number of documents automatically. The program DOC++ is used to generate HTML and LATEX from the C++ source code, LATEX2`HTML` is used to generate the HTML versions of the user's and developer's guide. We have included the sources of DOC++, so that it will be compiled and installed before you build the documentation. LATEX2`HTML` can be downloaded from `ftp.tex.ac.uk/tex-archive/support/latex2html` LATEX2`HTML` is written in Perl and you have to configure it yourself before you can use it on your system. This is all explained in the README file of LATEX2`HTML`.

- `lib/`. Here the object libraries (libglobal, libgui, libeditor, libdiagram and libtable) are stored after compilation. Furthermore this directory contains:
  - `lib/TCM` is the X Resources file. This file is not directly used by TCM (the default X resources of TCM are included in the source code), but it serves as a basis of your own modifications. You can load X resources with the `xrdb` command or by including them in some X-startup file like `$HOME/.Xdefaults`.
  - `lib/banner.ps` is a PostScript banner page. Normally this page is not printed but when you wish to print this banner page in front of your TCM documents, you can indicate this via the Printer Options sub-menu of in your editor or you can make this option the default by updating the `tcm.conf` file.
  - `lib/colorrgb.txt` is an ASCII file that maps TCM color names to red-green-blue (rgb) values.
  - `lib/help/` is a directory with the on-line help text files. The help files are all in ASCII format. These help texts are shown by the commands of the help-menu in the editors.
  - `lib/tcm.conf` is the TCM configuration file that is read upon start-up. It contains also some platform specific configuration options, like the name of the printer and the command to print or preview files. This file is intended to be human-readable and self-documenting. In stead of editing this file (which will affect all users of this TCM installation), you can also decide to override one or more options in a personal configuration file `$HOME/.tcmrc`. `.tcmrc` has the same syntax as `tcm.conf`. Note that some system specific configuration options such as the command to print or preview a document is commented out in `tcm.conf`. That is because TCM itself tries to determine these commands. Only if TCM can't find these commands or it chooses the wrong ones, you should set these as options explicitly by modifying `tcm.conf`.

- `man/` contains Unix man pages for TCM.
  - `man/man1/` contains short manual pages in nroff-format for each of the editors.
  - `man/windex` contains a simple index file that is used by `whatis` and `man -k`.

# 3.3 Object libraries

Depending on the operating system and the way TCM is compiled, object libraries are either shared object libraries, ending on `.so` or object archive libraries ending on `.a`. In the first case, the object code in the library is kept separated from the tool executables (they are dynamically linked), which makes executables smaller and run faster. For the Sun CC compiler (the default Solaris compiler) shared object libraries are made by default. For the other compilers such as `gcc` archive libraries are made by default. The contents of archive libraries are physically made part of the tool executables (they are statically linked); the libraries could be removed when compilation is completed.

Executables using object archive libraries tend to be much larger than with shared object libraries. Because of that, distributions that have to use archive libraries are in general compiled into only a few different executables, e.g. one for the tcm startup tool, one for all the diagram editors and one for all the table editors. The individual editors are then symbolic links to the collective diagram or table editor. The collective editor will see in its `argv[0]` argument which of the tools has to be launched.

Next: 4. TCM User Interface Up: Toolkit for Conceptual Modeling Previous: 2. System Architecture