You can set the following options without explicitly specifying them every time you invoke a compiler.

Just set the environment variable COMPILER_DEFAULTS_PATH to a colon-separated list of paths designating where the compiler is to look for the compiler.defaults file. If no compiler.defaults file is found, or if the environment variable is not set, the compiler looks in /etc/compiler.defaults . If this file is not found, the compiler resorts to the built-in defaults.

The compiler.defaults file contains a -DEFAULT: option group specifier that specifies the default ABI, ISA, and processor. The compiler issues a warning if you specify anything other than -DEFAULT: option in the compiler.defaults file.

The format of the -DEFAULT: option group is specified in each of the language manuals.

Use the -show_defaults option to print the compiler.defaults being used (if any) and their values. This option is for diagnostic purposes and does not compile any code.

Explicit command-line options override all compiler default settings, and the SGI_ABI environment variable overrides the ABI setting in the compiler.defaults file. The following command overrides a compiler.defaults file that sets -DEFAULT:abi=n32:isa=mips4:proc=r10k and compiles -64 -mips4 -r10000:

% cc -64 foo.c

The following command overrides the compiler.defaults file and sets the ABI to -o32 and the ISA to -mips2. The -o32 ABI supports only -mips2 (the default) and -mips1 compilations.

% cc -o32 foo.c

The processor type is ignored by -o32 compilations. Refer to the release notes and man pages for your compiler for information about default settings. Refer to the man pages for your command-line options.

You can set an environment variable (shown in Table 2-1) to specify the compilation mode to use.

How do you know when to use -n32 or -64 to compile your code? Compile -n32 when you want:

Compile -64 if your program:

The compiler system produces ELF object files. ELF is the format specified by the System V Release 4 Applications Binary Interface (the SVR4 ABI). ELF provides support for DSOs, described in the following section.

Types of ELF object files are as follows:

You can use this version of the compiler system to construct ABI-compliant executables that run on any operating system supporting the MIPS ABI. Be careful to avoid referencing symbols that are not defined as part of the MIPS ABI specification. For more information, see the following publications:

IRIX uses shared objects called Dynamic Shared Objects, or DSOs. The object code of a DSO is position-independent code (PIC), which can be mapped into the virtual address space of several different processes at once. DSOs are loaded at run time instead of at linking time by the run-time loader, rld . As is true of static shared libraries, the code for DSOs is not included in executable files; thus, executables built with DSOs are smaller than those built with non-shared libraries, and multiple programs may use the same DSO at the same time. For more information on DSOs, see Chapter 3, “Using Dynamic Shared Objects”.

Dynamic linking requires that all object code used in the executable be position-independent code (PIC). For source files in high-level languages, you just need to recompile to produce PIC. Assembly language files must be modified to produce PIC; see the MIPSpro Assembly Language Programmer's Guide for details.

Position-independent code satisfies references indirectly by using a global offset table (GOT), which allows code to be relocated simply by updating the GOT. Each executable and each DSO has its own GOT. For more information on DSOs, see Chapter 3, “Using Dynamic Shared Objects”.

The compiler system produces PIC by default when compiling higher-level language files. All of the standard libraries are provided as DSOs and therefore contain PIC code; if you compile a program into non-PIC, you will be unable to use those DSOs. One of the few reasons to compile non-PIC is to build a device driver, which does not rely on standard libraries.

Each compiler driver recognizes the type of an input file by the suffix assigned to the file name. Table 2-2 describes the possible file name suffixes.

The following example compiles preprocessed source code:

f77 -c tickle.i

The f77 compiler also assumes the file has already been preprocessed (because the suffix is .i) and therefore does not invoke the preprocessor.

Header files, also called include files, contain code that is inserted into the program.

C header files contain information about the libraries with which they are associated. They define such things as data types, data structures, symbolic constants, and prototypes for functions exported by the library. To use those definitions without having to type them into each of your source files, you can use the #include directive to tell the macro preprocessor to include the complete text of the given header file in the current source file. When you include header files in your source files, you can specify definitions conveniently and consistently in each source file that uses any of the library routines.

Fortran include files are specified by the INCLUDE line, which names a file containing source text. That source text is substituted for the INCLUDE line during compilation. The source text can be any Fortran code that is valid in the context of its location in the program.

By convention, C header file names have a .h suffix. Each programming language handles these files the same way, via the macro preprocessor. For example, the stdio.h header file describes, among other things, the data types of the parameters required by the C language printf() function.

For detailed information about standard header files and libraries, see the International Standard ISO/IEC, Programming languages--C, 9899, 1990. Also see “Using Typedefs ” in Chapter 6, for information about the inttypes.h header file.

#include <filename>

INCLUDE 'filename'

Creating a Header File for Multiple Languages

A single header file can contain definitions for multiple languages; this setup allows you to use the same header file for all programs that use a given library, no matter what language those programs are in.

To set up a shareable header file, create a .h file and enter the definitions for the various languages as follows:

#ifdef _LANGUAGE_C C Definitions #endif #ifdef _LANGUAGE_C_PLUS_PLUS C++ definitions #endif #ifdef _LANGUAGE_FORTRAN Fortran definitions #endif

---

Note: You must specify _LANGUAGE_ before the language name. To indicate C++ definitions, you must use _LANGUAGE_C_PLUS_PLUS , not _LANGUAGE_C++.

---

You can specify language definitions in any order.

This section describes the precompiled header mechanism that is available with the n32 and 64-bit C and C++ compilers. This mechanism is also available for C++ (but not C) in o32-bit mode.

This section contains the following topics:

#include “xxx.h”
#include “yyy.h”
int i;

#include “xxx.h”
#ifndef YYY_H
#define YYY_H 1
#include “yyy.h”
#endif
#if TEST
int i;
#endif

// a.C 
#include "xxx.h"

...                            // Start of code

// b.C 
#include "xxx.h"

...                            // Start of code

#include "xxx.h"
#include "yyy.h"
#include "zzz.h"

"test.C": creating precompiled header file "test.pch"

The relative overhead incurred in writing out and reading in a precompiled header file is quite small for reasonably large header files.

In general, writing out a precompiled header file does not cost much, even if it does not end up being used, and, if it is used, it almost always produces a significant speedup in compilation. The problem is that the precompiled header files can be quite large (from a minimum of about 250 Kbytes to several Mbytes or more), and so you probably do not want many of them sitting around.

You can see that, despite the faster recompilations, precompiled header processing is not likely to be justified for an arbitrary set of files with nonuniform initial sequences of preprocessing directives. The greatest benefit occurs when a number of source files can share the same PCH file. The more sharing, the less disk space is consumed. With sharing, the disadvantage of large precompiled header files can be minimized without giving up the advantage of a significant speedup in compilation times.

To take full advantage of header file precompilation, you should reorder the #include sections of your source files and group the #include directives within a commonly used header file.

The fecc source provides an example of how this can be done. A common idiom is the following:

#include "fe_common.h" 
#pragma hdrstop 
#include ...

In this example, fe_common.h pulls in, directly and indirectly, a few dozen header files. The #pragma hdrstop is inserted to get better sharing with fewer PCH files. The PCH file produced for fe_common.h is slightly over a megabyte in size. Another example, used by the source files involved in declaration processing, is the following:

#include "fe_common.h" 
#include "decl_hdrs.h"
#pragma hdrstop 
#include ...

decl_hdrs.h pulls in another dozen header files, and a second, somewhat larger, PCH file is created. In all, the fifty-odd source files of fecc share just six precompiled header files. If disk space is at a premium, you can decide to make fe_common.h pull in all the header files used. In that case, a single PCH file can be used in building fecc.

Different environments and different projects have different needs. You should, however, be aware that making the best use of the precompiled header support will require some experimentation and probably some minor changes to your source code.

Usually the compiler invokes the linker as the final step in compilation. If object files produced by previous compilations exist and you want to link them, invoke the linker by using a compiler driver instead of calling ld directly. Just pass the object file names to the compiler driver in place of source file names. If the original source files are in one language, invoke the associated driver and specify the list of object files.

In some cases you may need to invoke ld directly, such as when you are building a shared object or doing special linking not supported by compiler drivers (such as building an embedded system).

For information on the options available to the linker, see the ld man page.

% ld foiled.o again.o -lcurses

The assembler driver, as, does not run the linker. To link a program written in assembly language, use one of these procedures:

The linker processes its arguments from left to right as they appear on the command line. Arguments to ld can be object files, DSOs, or libraries. Be sure to list object files before DSOs.

When ld reads a DSO, it adds all the symbols from that DSO to a cumulative symbol table. If it encounters a symbol that is already in the symbol table, it does not change the symbol table entry. If you define the same symbol in more than one DSO, only the first definition is used.

When ld reads an archive, usually denoted by a file name ending in .a, it uses only the object files from that archive that can resolve currently unresolved symbol references. When a symbol is referred to but not defined in any of the object files that have been loaded so far, it is called unresolved.

Once a library has been searched in this way, it is never searched again. Therefore, place libraries after object files on the command line in order to resolve as many references as possible. If a symbol is already in the cumulative symbol table from having been encountered in a DSO, its definition in any subsequent archive or DSO is ignored.

Specifying Libraries and DSOs

You can specify libraries and DSOs either by explicitly stating a path name or by using the library search rules. To specify a library or DSO by path (either relative to the current directory or absolute), simply include that path on the command line:

% ld myprog.o /usr/lib/libc.so.1 mylib.so

---

Note: libc.so.1 is the name of the standard C DSO, replacing the older libc.a. Similarly, libX11.so.1 is the X11 DSO. Most other DSOs are simply named name.so, without a .1 extension.

---

To use the linker's library search rules, specify the library with the -lname option:

% ld myprog.o -lmylib

When the -lmylib argument is processed, ld searches for a file called libmylib.so. If it cannot find libmylib.so in a given directory, it tries to find libmylib.a there; if it cannot find that either, it moves on to the next directory in its search order.

The default search order uses the path appropriate to the compilation mode:

• For -n32, the default search order is /usr/lib32:/lib32.

• For -64, the default search order is /usr/lib64:/lib64.

• For -o32, the default search order is /usr/lib:/lib.

If ld is invoked from one of the compiler drivers, all -L and -nostdlib options are moved up on the command line so that they appear before any -l name options. For example, consider the command:

% cc file1.o -lm -L mydir

This command invokes, at the linking stage of compilation, the following:

% ld -L mydir file1.o -lm

---

Note: There are three different kinds of files that contain object code files: non-shared libraries, PIC archives, and DSOs. Non-shared libraries are the old-style library. PIC archives are the default, built using ar from .o files compiled with -KPIC (the default option). They can be linked with other PIC files. DSOs are built from PIC .o files by using ld -shared; see Chapter 3, “Using Dynamic Shared Objects”, for details.

---

If the linker tells you that a reference to a certain function is unresolved, check that function's man page to find out which library the function is in. If it is not in one of the standard libraries that ld links in by default, you may need to specify the appropriate library on the command line. For an alternative method of finding out where a function is defined, see “Finding an Unresolved Symbol with ld”.

---

Note: Simply including the header file associated with a library routine is not enough; you must also specify the library when linking (unless it is a standard library). No automatic connection exists between header files and libraries. Header files only give prototypes for library routines, not the library code itself.

---

Examples of Linking DSOs

To link a sample program foo.c with the math DSO, libm.so, enter:

% cc foo.c -lm

To specify the appropriate DSOs for a graphics program foogl.c , enter:

% cc foogl.c -lgl -lX11

---

Note: When linking, you must specify the source file name before the linker options.

---

This section describes how to link your source files with previously built DSOs; for more information about how to build your own DSOs, see Chapter 3, “Using Dynamic Shared Objects”.

To build an executable that uses a DSO, simply call a compiler driver. For instance, the following command links the resulting object file, needle.o, with the previously built DSO, libthread.so , and the standard C DSO, libc.so.1, if available.

% cc needle.c -lthread

If no libthread.so exists, but a PIC archive named libthread.a exists, that archive is used with libc.so.1 . So you still get dynamic (run-time) linking. Note that even .a libraries contain position-independent code by default, though it is also possible to build non-shared .a libraries that do not contain PIC.

The source language of the main program may differ from that of a subprogram. Follow the steps below to link multilanguage programs. For an illustration of the process, see Figure 2-1.

---

Note: Use caution when passing pointers and longs between languages, since some languages use different type sizes and structures for data types.

---

For specific details about compiling multilanguage programs, see the programming guides for the appropriate languages.

You can use ld to locate unresolved symbols. For example, suppose you are compiling a program, and ld tells you that you are using an unresolved symbol. You may not know where the unresolved symbol is referenced.

To find the unresolved symbol, enter:

% ld -ysymbol file1 ... filen

You can also enter:

% cc prog.o -Wl,-ysymbol

The output lists the source file that references symbol .

The dis tool disassembles object files into machine instructions. You can disassemble an object, archive library, or executable file.

See the dis(1) man page for descriptions of its options.

The dwarfdump tool provides debugging information from selected parts of DWARF symbolic information in an ELF object file. For more information on DWARF, including option descriptions, see the dwarfdump(1) and dwarf(4) man pages.

The elfdump tool lists headers, tables, and other selected parts of an ELF-format object file or archive file. See the elfdump(1) man page for option descriptions and other information.

The file tool lists the properties of program source, text, object, and other files. This tool attempts to identify the contents of files using various heuristics. It is not exact and often erroneously recognizes command files as C programs. For more information, including option descriptions, see the file(1) man page.

The nm tool lists symbol table information for object files and archive files. To get XPG4 (X/Open Portability Group) format, set the environment variable, _XPG in your environment.

For more information and option descriptions, see the nm(1) man page.

This example demonstrates how to obtain a symbol table listing. Consider the following program, tnm.c:

#include <stdio.h>
#include <math.h>
#define LIMIT 12
int unused_item = 14;
double mydata[LIMIT];

main()
{
      int i;
      for(i = 0; i < LIMIT; i++) {
          mydata[i] = sqrt((double)i);
      }
      return 0;
}

Compile the program into an object file by entering:

% cc -c tnm.c

To obtain symbol table information for the object file tnm.o in BSD format, use the nm -B command:

0000000000 T main
0000000000 B mydata
0000000000 U sqrt
0000000000 D unused_item
0000000000 N _bufendtab

To obtain symbol table information for the object file tnm.o in SVR4 format, use the nm command without any options:

Symbols from tnm.o:

[Index]   Value     Size    Class    Type         Section    Name

[0]     |        0|        |File    |ref=4       |Text     | tnm.c
[1]     |        0|        |Proc    |end=3 int   |Text     | main
[2]     |      116|        |End     |ref=1       |Text     | main
[3]     |        0|        |End     |ref=0       |Text     | tnm.c
[4]     |        0|        |File    |ref=6       |Text     | /usr/include/math.h
[5]     |        0|        |End     |ref=4       |Text     | /usr/include/math.h
[6]     |        0|        |Global  |            |Data     | unused_item
[7]     |        0|        |Global  |            |Bss      | mydata
[8]     |        0|        |Proc    |ref=1       |Text     | main
[9]     |        0|        |Proc    |            |Undefined| sqrt
[10]    |        0|        |Global  |            |Undefined| _gp_disp

The size tool prints information about the sections (such as text, rdata, and sbss) of the specified object or archive files. The elf(4) man page describes the format of these sections, and the size(1) man page describes the options accepted by the size command.

An example of the size command and the listings produced follows:

% size a.out

   Section         Size           Physical              Virtual
                                   Address              Address
         .interp     21          268435856            268435856 
   .MIPS.options    104          268435880            268435880 
        .dynamic    464          268435984            268435984 
        .liblist     20          268436448            268436448 
    .MIPS.symlib     30          268436468            268436468 
           .msym    240          268436500            268436500 
         .dynstr    312          268436744            268436744 
         .dynsym    720          268437056            268437056 
           .hash    256          268437776            268437776 
     .MIPS.stubs     56          268438032            268438032 
           .text    460          268438088            268438088 
           .init     24          268438548            268438548 
           .data     17          268505088            268505088 
          .sdata      8          268505108            268505108 
            .got    112          268505120            268505120 
            .bss     36          268505232            268505232 

The strip tool removes symbol table and relocation bits that are attached to the assembler and loader. Use strip to save space after you debug a program. The effect of strip is the same as that of using the -s option to ld.

See the strip(1) man page for descriptions of the options.

To create a new library, libtest.a, and add object files to it, enter:

% ar -cq libtest.a mcount.o mon1.o string.o

The -c option suppresses an archiver message during the creation process. The -q option creates the library and puts mcount.o, mon1.o, and string.o into it.

To replace an object file in an existing library, enter:

% ar -r libtest.a mon1.o

The -r option replaces mon1.o in the library libtest.a. If mon1.o does not already exist in the library libtest.a, it is added.

---

Note: If you specify the same file twice in an argument list of files to be added to an archive, that file appears twice in the archive.

---