News:New OpenGL management in Funtoo

Revision as of 12:12, March 1, 2015 by Mgorny (Talk | contribs) (example update command + explanation)

New OpenGL management in Funtoo

Funtoo is switching to an improved system for managing multiple OpenGL providers (Mesa/Xorg, AMD and nVidia). The update may involve blockers and file collisions.

By Mgorny / February 28, 2015

New OpenGL management

System principles

The new OpenGL management design assumes that the reference OpenGL implementation (mesa/Xorg) is to be used to build packages. After switching to the new system, all packages will use the mesa/Xorg headers and link to the mesa/Xorg libraries. This improves portability of software built on Funtoo and solves some of the build failures when non-standard OpenGL provider was enabled.

The third-party OpenGL libraries and modules provided by proprietary driver vendors can be enabled for run-time program use. They will not affect how the program is built. However, they will be loaded by the dynamic loader when starting executables. The Xorg server will also load the modules provided by blob driver vendor if appropriate.


The reference implementation (mesa/Xorg) packages install headers and libraries into standard system locations (/usr/include, /usr/lib*). The compiler and linker finds them using the usual rules and uses them.

The third-party OpenGL vendors install libraries and server extension modules into vendor-named subdirectories of /usr/lib*/opengl. Those files are not used directly.

Package:Eselect (OpenGL) is used to select OpenGL implementation used at run-time. The choice of implementation is controlled via dynamic linker configuration ( and Xorg server configuration. If the reference implementation is selected, the eselect module outputs null configuration that causes the linker and server to use the standard paths. If an another implementation is selected, the configuration prepends /usr/lib*/opengl paths to linker and server configuration, causing them to prefer the third-party libraries over reference.

Upgrade information

Before upgrade

Please note that the OpenGL subsystem upgrade is a lock-step update involving file collisions and blockers. This means that a few packages need to be upgraded consecutively during a single emerge run, and during that process the OpenGL support may become temporarily broken. If the upgrade is interrupted, your system may require manual attention.

Therefore, before upgrading please make sure that you can upgrade all the following packages, if installed:

  • x11-base/xorg-server to 1.16.4-r1 or newer,
  • media-libs/mesa to 10.3.4-r1 or newer,
  • x11-proto/glproto to 1.4.17-r1 or newer,
  • x11-drivers/ati-drivers to 14.9-r2 or newer,
  • app-emulation/emul-linux-x86-opengl to 20140508-r1 or newer.

If you need to use an older version of one of those packages long-term, please report a bug so that we can backport the support for the new system to it.

Additionally, please make sure to not enable FEATURES=collision-protect for the upgrade since it will involve replacing some of externally created symlinks with package files. FEATURES=protect-owned (enabled by default) is fine. If you don't want to disable FEATURES=collision-protect world-upgrade-wide, please see below for manual upgrade method.

The upgrade process

Normally, the upgrade should be performed as part of a regular @world upgrade.

However, if one desires to perform the upgrade stand-alone, he needs to pass all installed packages from the following list to emerge:

  • app-admin/eselect-opengl,
  • app-emulation/emul-linux-x86-opengl,
  • media-libs/mesa,
  • x11-base/xorg-server,
  • x11-drivers/ati-drivers,
  • x11-proto/glproto.

For example, the following command may be used to commence a manual update:

# FEATURES=-collision-protect emerge -1nu app-admin/eselect-opengl media-libs/mesa x11-base/xorg-server x11-proto/glproto


  1. FEATURES=-collision-protect will ensure that Portage can replace the symlinks created by old versions of eselect-opengl with real libraries.
  2. -1 will ensure that none of intermediate packages end up in @world, causing issues in the future,
  3. -n will prevent Portage from unnecessarily rebuilding packages that were upgraded already,
  4. -u will cause Portage to upgrade the remaining packages.

Post upgrade

There should be no manual steps needed after the upgrade. The currently selected OpenGL implementation will be activated automatically.

blog comments powered by Disqus