Project:AMD64/Fixing -fPIC Errors Guide

This guide is aimed at showing developers and interested users how to fix -fPIC errors

The problem
Sometimes gcc bails out with an error message like the following:

There are several different types of causes for such an error. This guide will not only explain them, but it will also show how to fix them.

What is PIC?
PIC is an abbreviation for Position-Independent Code. The following is an excerpt of the Wikipedia article about position-independent code:

"In computing, position-independent code (PIC) or position-independent executable (PIE) is object code that can execute at different locations in memory. PIC is commonly used for shared libraries, so that the same library code can be mapped to a location in each application (using the virtual memory system) where it won't overlap the application or other shared libraries. PIC was also used on older computer systems lacking an MMU, so that the operating system could keep applications away from each other.

Position-independent code can be copied to any memory location without modification and executed, unlike relocatable code, which requires special processing by a link editor or program loader to make it suitable for execution at a given location. Code must generally be written or compiled in a special fashion in order to be position independent. Instructions that refer to specific memory addresses, such as absolute branches, must be replaced with equivalent program counter relative instructions. The extra indirection may cause PIC code to be less efficient, although modern processors are designed to ameliorate this."

—Wikipedia Encyclopaedia

On certain architectures ( amongst them), shared libraries must be "PIC-enabled".

What are "relocations"?
Again, from Wikipedia:

"In computer science, relocation refers to the process of replacing symbolic references or names of libraries with actual usable addresses in memory before running a program. It is typically done by the linker during compilation, although it can be done at run-time by a loader. Compilers or assemblers typically generate the executable with zero as the lower-most, starting address. Before the execution of object code, these addresses should be adjusted so that they denote the correct runtime addresses."

—Wikipedia Encyclopaedia

With these terms defined, the prerequisites have been covered look at the different scenarios where breakage occurs:

Case 1: Broken compiler
At least GCC 3.4 is known to have a broken implementation of the  flag. The use of this flag is therefore highly discouraged, reported bugs are usually marked as RESOLVED INVALID. See for an example of a typical error message caused by this flag.

Case 2: Broken `-fPIC' support checks in configure
Many configure tools check whether the compiler supports the  flag or not. They do so by compiling a minimalistic program with the  flag and checking stderr. If the compiler prints any warnings, it is assumed that the  flag is not supported by the compiler and is therefore abandoned. Unfortunately, if the user specifies a non-existing flag (i.e. C++-only flags in  or flags introduced by newer versions of GCC but unknown to older ones), GCC prints a warning too, resulting in borkage.

To prevent this kind of breakage, the profiles use a bashrc script that filters out invalid flags in C[XX]FLAGS.

See bug for an example.

Case 3: Lack of `-fPIC' flag in the software to be built
This is the most common case. It is a real bug in the build system and should be fixed in the ebuild, preferably with a patch that is sent upstream. Assuming the error message looks like this:

This means that the file was not compiled with the   flag. This results in breakage. When this kind of error is addressed, make sure only objects that are used in shared libraries are compiled with.

In this case, globally adding  to C[XX]FLAGS resolves the issue, although this practice is discouraged because the executable end up being PIC-enabled as well.

Case 4: Linking dynamically against static archives
Sometimes a package tries to build shared libraries using statically built archives which are not PIC-enabled. There are two main reasons why this happens:

Often it is the result of mixing  and. If a library package can be built statically by setting, it usually does not create a  file but only a  archive. However, when GCC is given the  flag to link to said (dynamic or static) library, it falls back to the static archive when it cannot find a shared library. In this case, the preferred solution is to build the static library using the  flag too.

See and MySQL  for examples.

Sometimes it is also the case that a library is not intended to be a shared library at all, e.g. because it makes heavy usage of global variables. In this case the solution is to turn the to-be-built shared library into a static one.

See for an example.