Gentoo/AMD64 Howtos

Content:

• Gentoo/AMD64 Howtos
  Provides howtos for Gentoo/AMD64 users.
  1. Howto file bugs
     Provides information on howto file a bug related to the Gentoo/AMD64 Platform.
  2. 32Bit Chroot Guide for Gentoo/AMD64
     This guide will help you setup a 32Bit chroot for your Gentoo/AMD64 system.
  3. HOWTO fix -fPIC errors
     This HOWTO is aimed at developers and interested users showing how to fix -fPIC errors

A. Gentoo/AMD64 Howtos

1. Howto file bugs

1.a. How To File Keyword-Bugs On Gentoo/AMD64

First we want to thank you for helping out with the Gentoo/AMD64 project. Your diligent efforts in testing applications is greatly appreciated. In the following we want to explain the steps to submitting a bug report if you want to let us know that a masked application works on your Gentoo/AMD64 installation.

1.b. Register First!

If you haven't registered for an ID on bugs.gentoo.org, please do that first.

1.c. Steps For Submission

Perform the following steps to submit a bug:

• Browse to bugs.gentoo.org.
• Click on Report A Bug near the top of the page.
• Choose Gentoo Linux from the product list.
• Log in using your bugs.gentoo.org account.
• Search for your bug
  • Enter ALL and the name of the ebuild into the search textbox. Be carefull, ALL is casesensitive.

ALL k3b

• Continue searching for your bug
  • Click the Search button.
  • Check if anyone has already submitted a bug report on the masked application that works for you.
  • You should see two thing.
    • The Plt column should say amd64.
    • The Summary column should say something like working on amd64.
  • If you don't say anything applicable in the search subframe, move on to the next step. Otherwise, we already know about the application and you don't need to (and shouldn't) submit a new bug report.
• Give us your information
  • Select Ebuilds for the Component.
  • Select amd64 for the Hardware Platform.
  • In the Summary textbox, enter your summary in the form: ${category}/${application}-${version} works on amd64.

app-cdr/k3b-0.11.6 works on amd64

• Continue giving us info
  • In the Description textarea, enter a brief description in the from: Please add "~amd64" to the KEYWORDS for ${category}/${application}-${version}.

Please add "~amd64" to the KEYWORDS for app-cdr/k3b-0.11.6

• Continue giving us info
  • Paste the output from emerge info into the Description textarea. This step is very helpful and gives us the environmental conditions (e.g USE flags) you used.
  • Select Enhancement from the Severity drop-down listbox. Please don't select anything other here. The devs can (and will) change the severity of your bug report in case of nessesity.
• Doublecheck your work to make sure you've entered the correct data.
• Click Submit Bug Report when you're ready to file the report.

Thank you very much !

2. 32Bit Chroot Guide for Gentoo/AMD64

3. HOWTO fix -fPIC errors

3.a. The Problem

Sometimes it occurs that 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 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:

.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.

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.

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.

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

The contents of this document, unless otherwise expressly stated, are licensed under the CC-BY-SA-2.5 license. The Gentoo Name and Logo Usage Guidelines apply.