C.2. Postfix Compiling Primer

Before we move on to the specifics of building Postfix, let's take a look at some of the basics when compiling C code.

The options for a particular build are usually contained within a description file normally called Makefile. The make utility uses the Makefile to determine prerequisites, dependencies, and options to use when building a package. Using this information, make calls a compiler to create object files, and then a linker (usually called ld) to link them together into executables.

Since the Postfix distribution creates its own Makefile, you don't have to worry about editing that (and you shouldn't edit it, since any changes you make would likely get overwritten later). Options that Postfix needs in its Makefile are defined in environment variables such as CCARGS. The INSTALL file that comes with the Postfix distribution discusses all of the available options. We'll look at some of the more common ones here.

The following environment variables are available to set compile-time options. You should use quotes around the values to retain spaces or other shell metacharacters:

AUXLIBS

Tells the linker where to look for additional libraries that are not in the standard locations. For example, if you build support for an add-on package, you may have to indicate where the libraries are for that package.

CC

Specifies a particular compiler to use. If you want to use a compiler other than the one Postfix selects, set this variable to your compiler. Postfix normally uses gcc except on platforms where the native compiler is known to work better. You can check the makedefs file to see which compiler Postfix uses by default on your system.

CCARGS

Provides additional arguments to the compiler. If your compiler allows special options or your supporting files are not located in default directories, indicate those options with this variable.

DEBUG

The DEBUG parameter specifies debugging levels for the compiler to use when building the Postfix binaries. Turning on debugging produces extra information that a debugger can use. You can also turn off debugging features completely to build Postfix for a production system.

OPT

The OPT parameter specifies optimization levels for the compiler to use when building Postfix binaries. Additional optimization may increase performance but at the cost of longer compilation and more memory. You can probably accept the defaults that Postfix selects for your platform.

C.2.1 Compiler Options

Compiler options are set in the CCARGS variable. C source code files require header files that define certain functions and variables. The standard location for header files is the /usr/include directory. If your header files are located somewhere else, you have to tell the compiler where to look for them. The -I compiler option is used to specify additional directories where the compiler might find header files. If you are linking with libraries from external packages, the header files might be located where the package is installed rather than in the standard location. A common convention for external packages is to install header files in /usr/local/include. If you want to tell the compiler to look in that directory as well as the standard location when building Postfix, specify the options and directory with CCARGS:

CCARGS='-I/usr/local/include/'

Use additional -I options for each additional directory the compiler should search.

Postfix uses conditional compilation during its build, depending on which libraries or other resources are available on your system. It defines certain macros based on what it discovers about your system or based on options you have selected. The -D option provides a way to define macros at the time you compile Postfix. Add-on packages for Postfix require that you define a particular macro to tell Postfix to include it when building. For example, if you want to include support for MySQL, you define the HAS_MYSQL macro:

CCARGS='-DHAS_MYSQL'

C.2.2 Linker Options

Linker options are set in the AUXLIBS variable. After Postfix has compiled the object files, it links them together with required libraries into executable files. The standard location for system libraries is /usr/lib. To tell the linker to search additional directories for libraries, use the -L option:

AUXLIBS='-L/usr/local/lib'

You must also tell the linker which specific libraries to link in. The -l option is used to name specific libraries. The library files must be in a standard location or a directory indicated with the -L option. Library archive files are named starting with lib, followed by their name, followed by the extension, which is normally .a for static libraries and .so or .sl for shared objects or shared libraries. When you use the -l option, you leave off the initial lib and the extension of the library file. To link with the MySQL client library for example, where the library file is called libmysqlclient.a, the -l option is specified as follows:

AUXLIBS='-L/usr/local/lib -lmysqlclient'

Most linkers choose runtime or dynamic libraries over the static versions. Runtime libraries are linked when a program is running rather than during compilation. At compile time, the linker adds information so the program can find the libraries when it is executed. If you always install all of your dynamic libraries in a standard location such as /usr/lib, your system won't have any trouble finding the libraries at runtime. However, some external packages install libraries in nonstandard directories such that they cannot be found at runtime. Different systems use different conventions for locating dynamic libraries using fixed path information and environment variables. Be sure to configure your system to be able to find your dynamic libraries or make sure that the libraries are installed in your system's standard directories. Another option is to provide the actual path to specific libraries when you build your programs.

The linker uses an argument to include directories in a runtime search path for dynamic libraries. The argument differs depending on your linker and platform. The GNU linker (Linux, FreeBSD) uses -rpath, as does IRIX. Solaris, on the other hand uses -R, and HP-UX uses +b. Consult the manpage for your linker, ld(1), to see which argument you should use to set the runtime library search path.

Using the SSL library as an example, if your libssl.so file is located in /usr/local/lib and you are building Postfix on FreeBSD or another system that uses rpath, define AUXLIBS as follows:

AUXLIBS='-L/usr/local/lib -rpath/usr/local/lib -lssl'

When linking Postfix with external libraries, if you have multiple versions of the libraries installed, it is very important to make sure that you link Postfix with the version you need. Also, make sure that the library version you link to corresponds to the correct version of the header files you include. Version mismatch problems are often the source of compiler errors. Sometimes the compiler does not complain, in which case your build may succeed, but you're likely to find unusual errors from Postfix at runtime that can be tricky to track down.

gcc and Unrecognized Linker Options

Some versions of gcc do not understand all of the linker options you might use, and generate errors when compiling. The -rpath option is a common one. The compiler generates an error like gcc: unrecognized option '-rpath'. Since this option is really meant for the linker and gcc doesn't really have to recognize it, there is an easy workaround. The gcc compiler uses the -Wl, argument to indicate that certain options should be passed to the linker and otherwise ignored. In this case, when you specify the -rpath option, do it with -Wl:

AUXLIBS='-L/usr/local/lib -Wl,-rpath,/usr/local/lib -lssl'

See the gcc(1) manpage for more information.