FreeBSD Developers' Handbook
Prev	Chapter 2 Programming Tools	Next

2.4 Compiling with `cc`

This section deals only with the GNU compiler for C and C++, since that comes with the base FreeBSD system. It can be invoked by either cc or gcc. The details of producing a program with an interpreter vary considerably between interpreters, and are usually well covered in the documentation and on-line help for the interpreter.

Once you have written your masterpiece, the next step is to convert it into something that will (hopefully!) run on FreeBSD. This usually involves several steps, each of which is done by a separate program.

Pre-process your source code to remove comments and do other tricks like expanding macros in C.
Check the syntax of your code to see if you have obeyed the rules of the language. If you have not, it will complain!
Convert the source code into assembly language--this is very close to machine code, but still understandable by humans. Allegedly. [1]
Convert the assembly language into machine code--yep, we are talking bits and bytes, ones and zeros here.
Check that you have used things like functions and global variables in a consistent way. For example, if you have called a non-existent function, it will complain.
If you are trying to produce an executable from several source code files, work out how to fit them all together.
Work out how to produce something that the system's run-time loader will be able to load into memory and run.
Finally, write the executable on the filesystem.

The word compiling is often used to refer to just steps 1 to 4--the others are referred to as linking. Sometimes step 1 is referred to as pre-processing and steps 3-4 as assembling.

Fortunately, almost all this detail is hidden from you, as cc is a front end that manages calling all these programs with the right arguments for you; simply typing

    % cc foobar.c

will cause foobar.c to be compiled by all the steps above. If you have more than one file to compile, just do something like

    % cc foo.c bar.c

Note that the syntax checking is just that--checking the syntax. It will not check for any logical mistakes you may have made, like putting the program into an infinite loop, or using a bubble sort when you meant to use a binary sort. [2]

There are lots and lots of options for cc, which are all in the manual page. Here are a few of the most important ones, with examples of how to use them.

-o filename

The output name of the file. If you do not use this option, cc will produce an executable called a.out. [3]

    % cc foobar.c               executable is a.out
    % cc -o foobar foobar.c     executable is foobar

-c

Just compile the file, do not link it. Useful for toy programs where you just want to check the syntax, or if you are using a Makefile.

    % cc -c foobar.c

This will produce an object file (not an executable) called foobar.o. This can be linked together with other object files into an executable.

-g

Create a debug version of the executable. This makes the compiler put information into the executable about which line of which source file corresponds to which function call. A debugger can use this information to show the source code as you step through the program, which is very useful; the disadvantage is that all this extra information makes the program much bigger. Normally, you compile with -g while you are developing a program and then compile a ``release version'' without -g when you are satisfied it works properly.

    % cc -g foobar.c

This will produce a debug version of the program. [4]

-O

Create an optimised version of the executable. The compiler performs various clever tricks to try and produce an executable that runs faster than normal. You can add a number after the -O to specify a higher level of optimisation, but this often exposes bugs in the compiler's optimiser. For instance, the version of cc that comes with the 2.1.0 release of FreeBSD is known to produce bad code with the -O2 option in some circumstances.

Optimisation is usually only turned on when compiling a release version.

    % cc -O -o foobar foobar.c

This will produce an optimised version of foobar.

The following three flags will force cc to check that your code complies to the relevant international standard, often referred to as the ANSI standard, though strictly speaking it is an ISO standard.

-Wall: Enable all the warnings which the authors of cc believe are worthwhile. Despite the name, it will not enable all the warnings cc is capable of.
-ansi: Turn off most, but not all, of the non-ANSI C features provided by cc. Despite the name, it does not guarantee strictly that your code will comply to the standard.
-pedantic: Turn off all cc's non-ANSI C features.

Without these flags, cc will allow you to use some of its non-standard extensions to the standard. Some of these are very useful, but will not work with other compilers--in fact, one of the main aims of the standard is to allow people to write code that will work with any compiler on any system. This is known as portable code.

Generally, you should try to make your code as portable as possible, as otherwise you may have to completely rewrite the program later to get it to work somewhere else--and who knows what you may be using in a few years time?

    % cc -Wall -ansi -pedantic -o foobar foobar.c

This will produce an executable foobar after checking foobar.c for standard compliance.

-llibrary

Specify a function library to be used during when linking.

The most common example of this is when compiling a program that uses some of the mathematical functions in C. Unlike most other platforms, these are in a separate library from the standard C one and you have to tell the compiler to add it.

The rule is that if the library is called libsomething.a, you give cc the argument -lsomething. For example, the math library is libm.a, so you give cc the argument -lm. A common ``gotcha'' with the math library is that it has to be the last library on the command line.

    % cc -o foobar foobar.c -lm

This will link the math library functions into foobar.

If you are compiling C++ code, you need to add -lg++, or -lstdc++ if you are using FreeBSD 2.2 or later, to the command line argument to link the C++ library functions. Alternatively, you can run c++ instead of cc, which does this for you. c++ can also be invoked as g++ on FreeBSD.

    % cc -o foobar foobar.cc -lg++     For FreeBSD 2.1.6 and earlier
    % cc -o foobar foobar.cc -lstdc++  For FreeBSD 2.2 and later
    % c++ -o foobar foobar.cc

Each of these will both produce an executable foobar from the C++ source file foobar.cc. Note that, on Unix systems, C++ source files traditionally end in .C, .cxx or .cc, rather than the MS-DOS style .cpp (which was already used for something else). gcc used to rely on this to work out what kind of compiler to use on the source file; however, this restriction no longer applies, so you may now call your C++ files .cpp with impunity!

2.4.1 Common `cc` Queries and Problems

2.4.1.1. I am trying to write a program which uses the sin() function and I get an error like this. What does it mean?
2.4.1.2. All right, I wrote this simple program to practice using -lm. All it does is raise 2.1 to the power of 6.
2.4.1.3. So how do I fix this?
2.4.1.4. I compiled a file called foobar.c and I cannot find an executable called foobar. Where's it gone?
2.4.1.5. OK, I have an executable called foobar, I can see it when I run ls, but when I type in foobar at the command prompt it tells me there is no such file. Why can it not find it?
2.4.1.6. I called my executable test, but nothing happens when I run it. What is going on?
2.4.1.7. I compiled my program and it seemed to run all right at first, then there was an error and it said something about ``core dumped''. What does that mean?
2.4.1.8. Fascinating stuff, but what I am supposed to do now?
2.4.1.9. When my program dumped core, it said something about a ``segmentation fault''. What is that?
2.4.1.10. Sometimes when I get a core dump it says ``bus error''. It says in my Unix book that this means a hardware problem, but the computer still seems to be working. Is this true?
2.4.1.11. This dumping core business sounds as though it could be quite useful, if I can make it happen when I want to. Can I do this, or do I have to wait until there is an error?

2.4.1.1. I am trying to write a program which uses the sin() function and I get an error like this. What does it mean?

    /var/tmp/cc0143941.o: Undefined symbol `_sin' referenced from text segment

When using mathematical functions like sin(), you have to tell cc to link in the math library, like so:

    % cc -o foobar foobar.c -lm

2.4.1.2. All right, I wrote this simple program to practice using -lm. All it does is raise 2.1 to the power of 6.

    #include <stdio.h>
    
    int main() {
        float f;
    
        f = pow(2.1, 6);
        printf("2.1 ^ 6 = %f\n", f);
        return 0;
    }

and I compiled it as:

    % cc temp.c -lm

like you said I should, but I get this when I run it:

    % ./a.out
    2.1 ^ 6 = 1023.000000

This is not the right answer! What is going on?

When the compiler sees you call a function, it checks if it has already seen a prototype for it. If it has not, it assumes the function returns an int, which is definitely not what you want here.

2.4.1.3. So how do I fix this?

The prototypes for the mathematical functions are in math.h. If you include this file, the compiler will be able to find the prototype and it will stop doing strange things to your calculation!

    #include <math.h>
    #include <stdio.h>
    
    int main() {
    ...

After recompiling it as you did before, run it:

    % ./a.out
    2.1 ^ 6 = 85.766121

If you are using any of the mathematical functions, always include math.h and remember to link in the math library.

2.4.1.4. I compiled a file called foobar.c and I cannot find an executable called foobar. Where's it gone?

Remember, cc will call the executable a.out unless you tell it differently. Use the -o filename option:

    % cc -o foobar foobar.c

2.4.1.5. OK, I have an executable called foobar, I can see it when I run ls, but when I type in foobar at the command prompt it tells me there is no such file. Why can it not find it?

Unlike MS-DOS, Unix does not look in the current directory when it is trying to find out which executable you want it to run, unless you tell it to. Either type ./foobar, which means ``run the file called foobar in the current directory'', or change your PATH environment variable so that it looks something like

    bin:/usr/bin:/usr/local/bin:.

The dot at the end means ``look in the current directory if it is not in any of the others''.

2.4.1.6. I called my executable test, but nothing happens when I run it. What is going on?

Most Unix systems have a program called test in /usr/bin and the shell is picking that one up before it gets to checking the current directory. Either type:

    % ./test

or choose a better name for your program!

2.4.1.7. I compiled my program and it seemed to run all right at first, then there was an error and it said something about ``core dumped''. What does that mean?

The name core dump dates back to the very early days of Unix, when the machines used core memory for storing data. Basically, if the program failed under certain conditions, the system would write the contents of core memory to disk in a file called core, which the programmer could then pore over to find out what went wrong.

2.4.1.8. Fascinating stuff, but what I am supposed to do now?

Use gdb to analyse the core (see Section 2.6).

2.4.1.9. When my program dumped core, it said something about a ``segmentation fault''. What is that?

This basically means that your program tried to perform some sort of illegal operation on memory; Unix is designed to protect the operating system and other programs from rogue programs.

Common causes for this are:

Trying to write to a NULL pointer, eg

    char *foo = NULL;
    strcpy(foo, "bang!");

Using a pointer that has not been initialised, eg
```
    char *foo;
    strcpy(foo, "bang!");
           
```
The pointer will have some random value that, with luck, will point into an area of memory that is not available to your program and the kernel will kill your program before it can do any damage. If you are unlucky, it will point somewhere inside your own program and corrupt one of your data structures, causing the program to fail mysteriously.

Trying to access past the end of an array, eg

    int bar[20];
    bar[27] = 6;

Trying to store something in read-only memory, eg
```
    char *foo = "My string";
    strcpy(foo, "bang!");
           
```
Unix compilers often put string literals like "My string" into read-only areas of memory.

Doing naughty things with malloc() and free(), eg

    char bar[80];
    free(bar);

    char *foo = malloc(27);
    free(foo);
    free(foo);

Making one of these mistakes will not always lead to an error, but they are always bad practice. Some systems and compilers are more tolerant than others, which is why programs that ran well on one system can crash when you try them on an another.

2.4.1.10. Sometimes when I get a core dump it says ``bus error''. It says in my Unix book that this means a hardware problem, but the computer still seems to be working. Is this true?

No, fortunately not (unless of course you really do have a hardware problem...). This is usually another way of saying that you accessed memory in a way you should not have.

2.4.1.11. This dumping core business sounds as though it could be quite useful, if I can make it happen when I want to. Can I do this, or do I have to wait until there is an error?

Yes, just go to another console or xterm, do

    % ps

to find out the process ID of your program, and do

    % kill -ABRT pid

where pid is the process ID you looked up.

This is useful if your program has got stuck in an infinite loop, for instance. If your program happens to trap SIGABRT, there are several other signals which have a similar effect.

Alternatively, you can create a core dump from inside your program, by calling the abort() function. See the manual page of abort(3) to learn more.

If you want to create a core dump from outside your program, but do not want the process to terminate, you can use the gcore program. See the manual page of gcore(1) for more information.

[1]	To be strictly accurate, `cc` converts the source code into its own, machine-independent p-code instead of assembly language at this stage.
[2]	In case you did not know, a binary sort is an efficient way of sorting things into order and a bubble sort is not.
[3]	The reasons for this are buried in the mists of history.
[4]	Note, we did not use the `-o` flag to specify the executable name, so we will get an executable called `a.out`. Producing a debug version called `foobar` is left as an exercise for the reader!

Prev	Home	Next
Introduction to Programming	Up	Make

2.4 Compiling with cc

2.4.1 Common cc Queries and Problems

Notes

2.4 Compiling with `cc`

2.4.1 Common `cc` Queries and Problems