Gentoo Wiki


This article is part of the HOWTO series.
Installation Kernel & Hardware Networks Portage Software System X Server Gaming Non-x86 Emulators Misc


Howto use --hash-style including prelink

Warning: On gentoo boxes with binutils >= hashstyle=both is usually set as default. You can check that as described below (readelf -a ''random_binary'' | grep GNU_HASH). If so, enabling hashstyle and reemerging world is unnecessary.


Most applications make use of shared libraries, which can lead to long load times. Each library needs to be loaded at runtime to resolve symbols, etc. For most small programs this is very quick, but for programs written in C++ or those that have many linked libraries, this can take a fair amount of time.

One solution is prelinking. It's a method to perform the linking ahead of time and statically bind it to the executables. This increases the size of the executable a small bit, but allowed for some dramatic speedups in application start time. The problem with prelinking is that it has to be redone everytime a library changes and it does not work with dynamically loaded libraries. So applications that use dynamically loaded libraries, like OpenOffice, are not improved.

The next development occured through an improvement to binutils and glibc called direct linking, -Bdirect. This new method is not as effective as prelinking but it works for dynamically loaded libraries as well and does not require any prelinking step by the user. It was not officially adopted upstream but it's still being developed and might work with hashstyle one day.

About hashstyle

Hashstyle is fast becoming the next step, and patches have been merged into development releases upstream. This improvement is the new DT_GNU_HASH or .gnu.hash, now affectionately known as Hashstyle (due to the USE and ldflag naming). The new .gnu.hash is approximately 50% faster than the old sysv .hash.

Hashstyle is once again compatible with prelinking (assuming you get the latest elfutils and prelink) and adheres to ELF standards, unlike -Bdirect, which is why no patches have been merged upstream.

This wiki details how to migrate to the new hashstyles environment. Please be careful to read and re-read everything below before attempting to use this.


Using the hashstyle patches is unsupported by the Gentoo Linux Organization. By executing any actions below, you agree that all responsibility is yours. No responsibility is given to the author of this guide and its contributors. No help is guaranteed, but will be provided on the basis that you followed directions and are not beyond help. (In the case your system is no longer usable - system is equal to the gentoo installation, not your computer.)

First time install for hashstyle

Now we need to add the USE flag "hashstyle" to your USE variable in /etc/make.conf. I assume you know how to, since you are using experimental patches, so go ahead and do that.

Now you need to unmask an experimental binutils. At least version is required for gcc 4.x and for gcc 3.4.

Code: /etc/portage/package.keywords
sys-devel/binutils -*

If you want to use prelink you also need to unmask the latest version. You can skip this step if you are using unstable.

Code: /etc/portage/package.keywords

Now it's time for the fun part. Please make sure you have a backup before this, otherwise if anything screws up, there is no guarantee a method will be found to resurrect your system without reinstalling Gentoo.

# emerge binutils
# binutils-config -l
# binutils-config # (Replace # with the corresponding number to binutils-
# emerge glibc

Now add "-Wl,--hash-style=both" to your LDFLAGS in /etc/make.conf. If you do not have an LDFLAGS line, add this entire line then:

Code: /etc/make.conf

Important! Make sure you paste this line exactly. There is no space between the comma and the double dashes, and that's a lower case L after the -W.

Now we rebuild world with the new LDFLAGS to make sure that everything gets the new .gnu.hash section. Portage should run prelink automatically but I'm not positive it works 100%, so we will go ahead and prelink after this is done manually.

# emerge -e world
# emerge prelink
# prelink -amR

When it is completed you can check that it works by using readelf -a and grepĀ“ing for GNU_HASH on any binary. The output should look something like this:

# readelf -a /usr/bin/nano | grep GNU_HASH
  [ 4] .gnu.hash         GNU_HASH         00000000004009a0  000009a0
 0x000000006ffffef5 (GNU_HASH)           0x4009a0

More information about prelinking is available here:

Upgrade from patch version to newer version

For those of you who have already used the old patches (before 20060705), the new patches have an incompatible hash, so if you do not follow the next steps your system probably will be borked. This process will make your system unusable. Please DO NOT turn off the power to your computer until it is complete.

First make sure you have the latest overlay. Then remove the -Wl,--hash-style flag from your LDFLAGS and run:

# LD_X=1 emerge -1 coreutils binutils glibc

Add -Wl,--hash-style=both to your LDFLAGS again.

# LD_X=1 emerge -e world

Now we setup prelink

# emerge prelink
# prelink -amR

This has been tested.

Upgrade from old bdirect/hashvals to new hashstyle

First you need to remove "-Wl,-Bdirect -Wl,-hashvals -Wl,-zdynsort" from your LDFLAGS in /etc/make.conf.

Next we are going to emerge glibc from portage (unpatched glibc).

# PORTDIR_OVERLAY="" emerge -a1 glibc 

Then we emerge binutils (from portage) and glibc (from overlay) with new hashstyle use flag enabled.

  1. Please ensure you are emerging binutils >= below. If it isn't, please adjust package.keywords, etc.
  2. Please add hashstyle to your use flags for glibc (package.use).
# LD_X=1 emerge -1 binutils glibc

Now add "-Wl,--hash-style=both" to your global LDFLAGS in /etc/make.conf.

# LD_X=1 emerge -e world

This has been tested successfully (roderick 19:50, 31 July 2006 (UTC))

Now we are free to emerge/setup prelink (requires elfutils >= 0.122 and prelink >= 20060712)

# emerge prelink
# prelink -amR

Remember to remove the LD_BIND_DIRECT="1" from your environment after you rebuild. Not sure if it will cause any problems, but it is probably best to get rid of it. Most people would have put it in "/etc/env.d/99local" (or somewhere in /etc/env.d).

Post Messages

Well you should now have a prelinked system with --hash-style=both. If all went well, you are now free to do as you please. If this ruined your system, I'm sorry, but I did warn you.

Known Issues

<=madwifi-ng- (latest current version, Feb 11 2007 -- the cvs version too) is known to refuse linking (ld does not recognize hal.o file format) with >=binutils- (not with older versions).

To use madwifi-ng you only need to temporarily downgrade your binutils to compile it and it will work.

=x11-drm-20070314 (latest version gets an error about unknown LDFLAGS) (have not tested others, was building with VIDEOCARDS="radeon") simply emerge it with LDFLAGS=" "


If your system screwed up, and you get a bunch of symbol errors when running any application, please use LD_X=1 <command>. This should allow you to temporarily use the application until you get it fixed.

I will post more in the Troubleshooting section regarding fixing a broken system soon.

The Gentoo Forums thread for hashstyle is:

Retrieved from ""

Last modified: Fri, 05 Sep 2008 07:01:00 +0000 Hits: 19,203