Author:                             Antonomasia
Email Address:                      ant@notatla.demon.co.uk
Web Page:                           http://www.notatla.demon.co.uk
One-line summary of topic\question: Compiling Programs
Original date of FAQ topic:         16 August 1997
Date FAQ topic was last modified:   31 August 1997

Compiling Programs

This is not about SRPM packages that work right away.
It is about compiling programs that have not come as an SRPM,
perhaps you wish to write a program, or alter an existing one.


PRINCIPLES

Roughly speaking, a program is something a computer can execute,
such as  those nice things on your HD.  Somebody wrote the
'source code' in a language he/she could understand, or was
supposed to.  That might have been C (very likely) or Fortran
or some such thing.

The program 'source code' also makes sense to a compiler that converts
the instructions into a binary file suited to whatever processor is
wanted - eg a 386 or similar.  Red Hat distributions are different for
the supported platforms of Intel, Sparc and Alpha for this reason.
A modern file format for these 'executable' programs is Elf.

The programmer shows his source to the compiler and gets a result
of some sort.   It's not at all uncommon that early attempts fail
to compile, or having compiled, fail to act as expected. 
Half of programming is tracking down and fixing these problems (debugging).

The parts of the task are:           (typical values,
                                      vary with experience and dedication)

   a  deciding what to program in the first place     40%
   b  extending the original plan                     50%
   c  debugging                                       50%
   d  checking details of the language                15%
   e  arranging portability and speedups              10%
   f  testing                                         10%
   g  documenting the product                         10%

And you wondered why programs are always late !
Do not skimp on step 'a' whatever you do.  That leads
to disaster almost for certain.


EXAMPLES

It would be easy to get sidetracked into programming issues here.
But we'll keep to the subject and look at a small example compilation:

One-File Programs

      (the next 6 lines are the source, in the file 'echo.c')
#include <stdio.h>
main (int argc,  char **argv) {
int i;
if (argc < 1) exit(9);
for (i=argc-1 ;i;i--) printf("%d %s\n",i,argv[i]);
}

gcc echo.c      # This command compiles 'echo.c' and produces 'a.out'.

We can now run 'a.out' with some arguments.
a.out one two three four

And we get this output.
4 four
3 three
2 two
1 one

More complicated setups involve:
           multiple files
           makefiles
           libraries
           patches


Multiple Files
One-file programs are quite rare.  Usually there are a number of
files (say *.c) that are each compiled into object files (*.o)
and then linked into an executable.  The compiler is usually used
to perform the linking (and it calls 'ld' behind the scenes).


Makefiles
These are intended to aid consistency (you build your program the
same way each time).  They also often help with speed.  Some compiles
are quite long - tens of minutes for a large program.  The 'make' program
uses 'depenencies' in the Makefile to decide what parts of the program
need to be recompiled.  If you change one source file out of fifty you
hope to get away with one compile and one link step, instead of starting
from scratch.  The best advice for beginner Makefile writers (and just
about any other writers) is - find one that works and copy it.  Be aware
that the format includes tabs at the start of some lines (spaces won't do).


Libraries
Programs can be linked not only to object files (*.o) but also to
libraries (collections of object files).  You will sometimes have to
link to system-supplied libraries (e.g. -lm for the maths library, without
which your mathematical C programs will produce nonsense).  You might
sometimes want to package a few of your object files into a library
if you intend to use them often.  There are two forms of linking to
libraries: static (the code goes in the executable file) and
           dynamic (the code is collected when the program starts to run).
Large compiler manuals spend a page discussing the pros and cons of the two.


Patches
Before my time I understand it was common for executable files to
be given corrections without recompiling them.  This practice has
deservedly almost died out.  Now people 'patch' source code, putting
a change into files (usually changing a small proportion of the whole).
Larry Wall's 'patch' program is used for this.  Where different versions
of a program are required small changes to code can be released, saving
the trouble of having two large distributions.  Red Hat packages work
like this, including 'pristine source' and usually some patches.


Errors in Compilation and Linking
These are often typos, omissions, misuse of the language ....
Check that the right include files are used for the functions
you are calling (RT.M).  Unreferenced symbols are the sign of
an incomplete link step.


Debugging
This is a large topic.  It usually helps to have statements in the code
that inform you of what is happening.  To avoid drowning in output you
might sometimes get them to print out only the first 3 passes in a loop.
Checking that variables have passed correctly between modules often helps.
Get familiar with your debugging tools.
