Content:

• The Problem
• What is PIC?
• What are "relocations"?
• Case 1: Broken compiler
• Case 2: Broken `-fPIC' support checks in configure
• Case 3: Lack of `-fPIC' flag in the software to be built
• Case 4: Linking dynamically against static archives

3.a. The Problem Sometimes it occurs that gcc bails out with an error message like the following: Code Listing 1.1: A typical gcc error message .libs/assert.o: relocation R_X86_64_32 against `a local symbol' can not be used when making a shared object; recompile with -fPIC .libs/assert.o: could not read symbols: Bad value There are several different types of causes for such an error. This HOWTO will explain all of them and show how to fix them. 3.b. 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 (AMD64 amongst them), shared libraries must be "PIC-enabled". 3.c. 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, we can finally have a look at the different scenarios where breakage occurs: 3.d. Case 1: Broken compiler At least GCC 3.4 is known to have a broken implementation of the -fvisibility-inlines-hidden flag. The use of this flag is therefore highly discouraged, reported bugs are usually marked as RESOLVED INVALID. See bug 108872 for an example of a typical error message caused by this flag. 3.e. Case 2: Broken `-fPIC' support checks in configure Many configure tools check whether the compiler supports the -fPIC flag or not. They do so by compiling a minimalistic program with the -fPIC flag and checking stderr . If the compiler prints *any* warnings, it is assumed that the -fPIC 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 CFLAGS 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 AMD64 profiles use a bashrc that filters out invalid flags in C[XX]FLAGS . See bug bug 122208 for an example. 3.f. 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: Code Listing 6.1: A sample error message .libs/assert.o: relocation R_X86_64_32 against `a local symbol' can not be used when making a shared object; recompile with -fPIC .libs/assert.o: could not read symbols: Bad value This means that the file assert.o was not compiled with the -fPIC flag, which it should. When you fix this kind of error, make sure only objects that are used in shared libraries are compiled with -fPIC . In this case, globally adding -fPIC to C[XX]FLAGS resolves the issue, although this practice is discouraged because the executables end up being PIC-enabled, too. Note: Adding the -fPIC flag to the linking command or LDFLAGS won't help. 3.g. 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 USE=static and USE=-static . If a library package can be built statically by setting USE=static , it usually doesn't create a .so file but only a .a archive. However, when GCC is given the -l flag to link to said (dynamic or static) library, it falls back to the static archive when it can't find a shared lib. In this case, the preferred solution is to build the static library using the -fPIC flag too. Warning: Only build the static archive with -fPIC on AMD64. On other architectures this is unneeded and will have a performance impact at execution time. See bug 88360 and mysql bug 8796 for an example. Sometimes it is also the case that a library isn't 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 bug 131460 for an example. Code Listing 7.1: A sample error message gcc -fPIC -DSHARED_OBJECT -c lex.yy.c gcc -shared -o html2txt.so lex.yy.o -lfl usr/lib/gcc/x86_64-pc-linux-gnu/4.1.1/../../../../x86_64-pc-linux-gnu/bin/ld: /usr/lib/gcc/x86_64-pc-linux-gnu/4.1.1/../../../../lib64/libfl.a(libyywrap.o): relocation R_X86_64_32 against `a local symbol' can not be used when making a shared object; recompile with -fPIC /usr/lib/gcc/x86_64-pc-linux-gnu/4.1.1/../../../../lib64/libfl.a: could not read symbols: Bad value