Next: 4. TCM User Interface
Up: Toolkit for Conceptual Modeling
Previous: 2. System Architecture
Subsections
3. Source Code Organization
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:
- 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,
LATEX2HTML 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. LATEX2HTML can be downloaded from
ftp.tex.ac.uk/tex-archive/support/latex2html
LATEX2HTML 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 LATEX2HTML.
- 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.
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
Henk van de Zandschulp
2003-01-07