The Linux GCC HOWTO

Daniel Barlow

Linux Documentation Project

May 1999

This document covers how to set up the GNU C compiler and development libraries under Linux, and gives an overview of compiling, linking, running and debugging programs under it. Most of the material in it has been taken from Mitch D'Souza's GCC-FAQ or the ELF-HOWTO - it replaces both documents.

This is the first version to be written in DocBook instead of the old Linuxdoc format, and may contain markup errors. Please let me know if you find anything worng.

As can be determined from the long times between updates of this document, I don't actually have the time or inclination to maintain it much. If you have, can, and want to, drop me some email describing what you'd do with it and why you think you'd be good at it.


Table of Contents
1. Preliminaries
1.1. ELF vs. a.out, libc 5 vs 6
1.2. Administrata
1.3. Typography
2. Where to get things
3. GCC installation and setup
3.1. GCC versions
3.2. Where did it go?
3.3. Where are the header files?
3.4. Building cross compilers
3.4.1. Linux as the target platform
3.4.2. Linux as the source platform, MSDOS as the target
4. Porting and Compiling
4.1. Automatically defined symbols
4.2. Compiler invocation
4.2.1. Compiler flags
4.2.2. Internal compiler error: cc1 got fatal signal 11
4.3. Portability
4.3.1. BSDisms (including bsd_ioctl, daemon and <sgtty.h>)
4.3.2. `Missing' signals (SIGBUS, SIGEMT, SIGIOT, SIGTRAP, SIGSYS etc)
4.3.3. K & R Code
4.3.4. Preprocessor symbols conflict with prototypes in the code
4.3.5. sprintf()
4.3.6. fcntl and friends. Where are the definitions of FD_* stuff ?
4.3.7. The select() timeout. Programs start busy-waiting.
4.3.8. Interrupted system calls.
4.3.9. Writable strings (program seg faults randomly)
4.3.10. Why does the execl() call fail?
5. Debugging and Profiling
5.1. Preventative maintenance (lint)
5.2. Debugging
5.2.1. How do I get debugging information into a program ?
5.2.2. Available software
5.2.3. Background (daemon) programs
5.2.4. Core files
5.3. Profiling
6. Linking
6.1. Shared vs static libraries
6.2. Interrogating libraries (`which library is sin() in?')
6.3. Finding files
6.4. Building your own libraries
6.4.1. Version control
6.4.2. ELF? What is it then, anyway?
6.4.3. a.out. Ye olde traditional format
6.4.4. Linking: common problems
7. Dynamic Loading
7.1. Concepts
7.2. Error messages
7.3. Controlling the operation of the dynamic loader
7.4. Writing programs with dynamic loading
8. Contacting the developers
8.1. Bug reports
8.2. Helping with development
9. The Remains
9.1. The Credits
9.2. Translations
9.3. Feedback
9.4. Legalese

1. Preliminaries

1.1. ELF vs. a.out, libc 5 vs 6

Three years ago when this document was first created, I opened this section by saying "Linux development is in a state of flux right now" and going on to describe how ELF was replacing the older a.out binary format.

It still is in a state of flux. It always will be. Though that particular change is long since past, development of the Linux kernel and the surrounding system continues to happen, and things change for developers as a result. So it's a good idea to know upfront what kind of system you have in front of you.

The possible candidates, in order of age, are

  • libc 4, a.out: very old systems

  • libc 5, ELF: Red Hat 4.2, Debian 2.0

  • libc 6 (a.k.a glibc 2), ELF: Red Hat 5 - 5.2, Debian 2.1

  • libc 6.1,(a.k.a glibc 2.1) ELF: Red Hat 6

How to tell? The simplest approach is to pick a binary that you consider is typical (e.g. /bin/ls and run ldd on it. One of the listed libraries should be libc - check its version number.
$ ldd /bin/ls
        libc.so.6 => /lib/libc.so.6 (0x4000e000)
        /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)

This document was created on a Debian 2.1 system, so no surprise there.

It's entirely possible that the system you're using may have a mix of different versions on it. What you probably want to know in that case is the version that its C development environment is set up for, so you're best off compiling "hello world" and running ldd on the output thus created. Note that for historical reasons, gcc defaults to an output file called a.out even on ELF systems, so don't assume anything from that.



1.2. Administrata

The copyright information and like legalese can be found at the end of this document, together with the statutory warnings about asking dumb questions on Usenet, revealing your ignorance of the C language by reporting bugs which aren't, and picking your nose while chewing gum.

1.3. Typography

If you're reading this in Postscipt, dvi, or html format, you get to see a little more font variation than people with the plain text version. In particular, filenames, commands, command output and source code excerpts are set in some form of typewriter font, whereas `variables' and random things that need emphasizing are emphasized.

You also get a usable index. In dvi or postscript, the numbers in the index are section numbers. In HTML they're just sequentially assigned numbers that you can click on. In the plain text version, they really are just numbers. Get an upgrade!

The Bourne (rather than C) shell syntax is used in examples. C shell users will want to use

% setenv FOO bar
where I have written
 
$ FOO=bar; export FOO


If the prompt shown is # rather than $, the command shown will probably only work as root. Of course, I accept no responsibility for anything that happens to your system as a result of trying these examples. Have a nice day :-)