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:
.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 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 (amd64 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 -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.
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 script that filters out invalid flags in C[XX]FLAGS.
See bug bug #122208 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:
.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. This results in breakage. When this kind of error is addressed, 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 executable end up being PIC-enabled as well.
Adding the
-fPIC flag to the linking command or LDFLAGS will not help.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 does not 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 cannot find a shared library. In this case, the preferred solution is to build the static library using the -fPIC flag too.
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 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 bug #131460 for an example.
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
This page is based on a document formerly found on our main website gentoo.org.
The following people contributed to the original document: Tom Martin (maintainer), Simon Stelling (maintainer), last updated July 23, 2006
They are listed here because wiki history does not allow for any external attribution. If you edit the wiki article, please do not add yourself here; your contributions are recorded on each article's associated history page.