Re: specifications

[Feloy <feloy@free.fr>]

I wrote:
> 
> But the idea requires careful thought : I began to write a tutorial for
> GNU tools (GCC and MAKE at this time), and I'll try to turn this manual
> into man pages.
> 

So here a first test of a learn page about C compilation.

I know that my english is poor, sorry.
French people can get a french version at 
http://feloy.free.fr/gcc.1.fr
.TH gcc_learn 1
.SH NOM
gcc - GNU Project C Compiler
.SH FILE TYPES
.TP
.B C Source (.c)
This is generally in this format you write your programs.
.TP
.B Preprocessed C Source (.i)
The C source files include other files and/or use macros. A
preprocessed C file is the image of the C file after inclusion of
files and/or expansion of macros.
.TP
.B Assembler source (.S), preprocessed (.s)
The assembler language is a non portable language which describes
your program like a (nearly) linear series of instructions
executed by the processor. 

This language is almost never used nowadays, but it is possible
you have to use it, or have to stop the compilation process at
this step to see how the computer will really execute some part of
your program. 
.TP
.B Preprocessor file (.h)
File included in C or assembler source files, generally
containing function definitions, variable definitions, macros
definitions and so on. 
.TP
.B Object file (.o)
This file is not a text file like the others, but a binary
file. You will not need to edit it. An object file is the image
of one (and only one) C or assembler source file. It is readable
by the computer (or the kernel to be precise).
.TP
.B Executable file
This is the file you will run. This file is the union of
all the necessary object files. Links are created between object
files, so a part of one object file can call a part of
another object file (in the C source point of view, a fonction
written in one source file can call a function written in another
source file).
.SH COMPILATION STAGES
The C compiler (
.B gcc
) processes files through different stages. By default, the
.B gcc
command executes all these stages on the files given in the
command line, unless you specify an option to stop after one
of these stages.
.TP
.B preprocessing
includes files and expands macros in a C or assembler source file:

Use the
.B \-E
option to stop
.B gcc
after preprocessing.
.TP
.B compilation
converts a C source file into an assembler source file:

Use the
.B \-S
option to stop
.B gcc 
after compilation.
.TP
.B assembly
converts an assembler source file into an object file:

Use the
.B \-c
option to stop
.B gcc
after assembly.
.TP
.B linking
groups and links the object files to create the executable.
.SH EXAMPLE
You have written a program to play solitaire, in C and assembler,
and sources are divided into different files:

.sp
.B cards.c and distribute.c
.RS
C source files.
.RE
.B draw.s
.RS
Assembler source file with inclusion and macros.
.RE
.B points.S
.RS
Assembler source file without inclusions nor macros.
.RE
.sp
Here is how to realise one, several or all the stages of the
compilation.
.TP
.B Linking
If you want to directly obtain the executable from all the source
files, use the command:
.sp
.nf
% gcc cards.c distribute.c draw.s points.S -o cards
.fi
.sp
You obtain the executable
.BR "cards" "."
.sp
.TP
.B Assembly
If you want to obtain all the object files, use the command:
.sp
.nf
% gcc -c cards.c distribute.c draw.s points.S
.fi
.sp
You obtain the files
.BR "cards.o" ", " "distribute.o" ", " "draw.o" " and " "points.o" "."
.sp
.TP
.B Compilation
If you want to compile your source files and obtain the assembler
sources, use the command:
.sp
.nf
gcc -S cards.c distribute.c draw.s points.S
.fi
.sp
You obtain the files
.BR "cartes.s" " et " "distribuer.s" ", "
but the files
.BR "dessiner.s" " et " "points.S"
remain unchanged.
.sp
.TP
.B Preprocessing
If you want to preprocess one of your source file, for example to
see how your macros are expanded, use the command:
.sp
.nf
gcc -E cards.c > cards.i
.fi
.sp
.B Careful :
In this case,
.B gcc
just uses the first file given in the command line and writes the
preprocessing result to the standard output.