From source to executable

A program in source form can be fun to read, but sources are rather useless if they can not be transformed into something executable. This section will detail the steps involved in turning TOM source into an executable. If you are not interested in the details, you can safely skip this and continue to read the next section (1.4, page ), which explains how you'd normally compile TOM programs.

The first step is creating the source file containing our example program. You can enter the example from the previous section manually or simply copy copy it from /usr/local/tom/ttpl/ex/hello.t^1.1. In any case, you should end up with a file hello.t in a preferrably empty directory.

The next thing to do is to run the interface generator, gi. Apart from its main task--generating interfaces; hence its name--it is also responsible for creating the so-called unit file. A unit is the largest building block in TOM. A program is a unit, and each library is also a unit. The unit file declares which classes are defined in every file contained in the unit.

We will elaborate on the interface generator later on. For now it is important to know that you must run it because it will generate the unit file. Accomplish this by entering the following command line^1.2:

$ gi -u hello -U tom hello.t

00.5cm (You don't actually enter the $. It is here to remind you that the line is a shell command.) This command tells gi:

to -u hello

To create the unit file for the unit hello. The name of the unit file is the name of the unit, with the extension .u. Thus our example unit file will be called hello.u.

to -U tom

The unit hello depends on the unit tom. The tom unit contains, among different kinds of useful objects, such as the stdio class used in our example program, also the runtime library which is necessary for executing TOM programs.

to hello.t

This is the single file in our example unit.

Now that all necessary files are in place, it is time to run the compiler, which will turn a TOM source file into a C source file. Enter the following command:

$ tomc -1 -u hello -I $prefix/lib/tom hello

tomc is the TOM compiler. After it has verified that the unit file of the unit hello indeed contains the file hello, it reads hello.t and produces hello.c. The -I directive points tomc at the standard library units: $prefix usually is /usr or /usr/local.

Next, we let the C compiler do its work. The code produced by tomc can only be compiled by the GNU C Compiler (gcc), since it employs gcc specific constructs.

$ gcc -c hello.c

This turns the file hello.c into hello.o, which is the object file corresponding to the TOM source file hello.t.

Normally, a unit contains several source files, and you must run both tomc and gcc for every file in the unit.

When all files have been compiled--only hello.t in our example--you'd expect time has come to link the object files, with any libraries needed, to create the executable. However, when building a TOM program, one extra step is needed before the linking: the resolver must be run to build the data structures needed by the runtime library.

$ tomr -1 -I $prefix/lib/tom -u hello

Similar to tomc, tomr operates on the unit file in the current directory. It creates a C source file containing the run-time datastructures of the hello unit. In our example, it will create hello-r.c. Obviously, this needs to be compiled too.

$ gcc -c hello-r.c -I $prefix/lib/tom

Now we're really done compiling and the objects can be linked together to form the executable^1.3.

$ gcc -L $prefix/lib -o hello hello.o hello-r.o -ltom -ltrt

Obviously, the objects hello.o and hello-r.o are linked against the TOM library object, the trt TOM Run-Time library, and any implict libraries included by gcc. When you've successfully completed the above steps, you can now run Your First TOM Program.

$ ./hello
Hello, world!