The Problem Domain

We have multiple, often hardware dependent, implementations of the Khronos EGL, GL|ES, and OpenVG APIs. We want software in the Ubuntu archive to be able to build against these APIs. Software in the Ubuntu archive must build against the Mesa implementation.

With the introduction of MultiArch support in dpkg we should also support the parallel install of EGL packages from different sources for different architectures - for example, to allow a developer on an x86-64 system to use the x86-64 EGL implementation from the proprietary ATI drivers while having an armel EGL implementation from mesa installed to cross-compile for ARM.

The goal is to have multiple EGL implementations available in the Ubuntu archive

Assumptions

• The selection of EGL implementation determines which GL|ES and OpenVG implementation is usable. For example, it would never be useful to use a vendor's GLESv2 library with Mesa's EGL.

• The libraries (with SONAME) are libEGL.so.1, libGLESv1_CM.so.1, libGLESv2.so.2 and libOpenVG.so.1

Packaging

Multiarch

This is a brief summary as it applies to EGL libraries. See the MultiarchSpec for full details.

Throughout this guide DEB_HOST_MULTIARCH is used as a variable. The appropriate value for this variable on an Ubuntu system can be found by running dpkg-architecture -qDEB_HOST_MULTIARCH. The most common values for DEB_HOST_MULTIARCH are arm-linux-gnueabi for armel, i386-linux-gnu for i386, and x86_64-linux-gnu for amd64.

If vendor drivers are only available for a single architecture then the rest of this section may be skipped. The traditional /usr/lib library paths still function as normal on a multiarch system, and there is no technical impediment to switching to multiarch packaging later.

To allow for the same package built for different architectures to be installed at the same time the library paths must be unique for each architecture (dpkg has special handling for data in /usr/share). Libraries for a multi-arch ready EGL package must live in a subdirectory of /usr/lib/$DEB_HOST_MULTIARCH/. The value of DEB_HOST_MULTIARCH can be retrieved with from dpkg-architecture -qDEB_HOST_MULTIARCH. For example, libraries for the amd64 architecture live in /usr/lib/x86_64-linux-gnu/.

There is (at the moment) no equivalent policy for -dev packages.

Alternatives

To support FIXME the previous Conflicts/Provides/Replaces solution is no longer appropriate as it precludes having the Mesa EGL libraries for one architecture and a vendor's EGL libraries for the native architecture simultaneously installed. We instead use the Debian alternatives system to provide a per-architecture switch.

Packages which use this alternatives system should not provide the libegl1-x11, libgles1, libgles2 or libopenvg1 virtual packages.

Each EGL implementation should install their libraries into a subdirectory of libdir, which should be of the form $VENDOR-egl. The implementation should also install a ld.so.conf file, containing the fully qualified directory name. For example, on x86-64, Mesa's implementation is installed into /usr/lib/x86_64-linux-gnu/mesa-egl, and has a /usr/lib/x86_64-linux-gnu/mesa-egl/ld.so.conf file containing the line

/usr/lib/x86_64-linux-gnu/mesa-egl

The current EGL implementation is selected by setting the $DEB_HOST_MULTIARCH_egl_conf alternative. This alternative will set /etc/ld.so.conf.d/$DEB_HOST_MULTIARCH_EGL.conf to point to the current implementation's ld.so.conf. The dynamic loader will then search the implementation's private libdir when attempting to resolve libraries.

The package which provides libEGL.so.1 is responsible for setting the alternative. If the GL|ES or OpenVG libraries are in separate packages, they should be installed alongside libEGL.so.1 and should not touch the alternatives configuration.

debian/rules example snippet

        # Create an ld.so.conf which says where to find libEGL, libGLES{1,2} 
        # and libOpenVG from Mesa.

        echo "/usr/lib/$(DEB_HOST_MULTIARCH)/mesa-egl" \
        > $(CURDIR)/debian/libegl1-mesa/usr/lib/$(DEB_HOST_MULTIARCH)/mesa-egl/ld.so.conf

postinst example

set -e

THIS_PACKAGE=libegl1-mesa
THIS_SCRIPT=postinst

case "$1" in
  configure)
  # Use alternatives to make it easier to switch between Mesa and 3rd party modules
  update-alternatives --force \
    --install /etc/ld.so.conf.d/${DEB_HOST_MULTIARCH}_EGL.conf ${DEB_HOST_MULTIARCH}_egl_conf /usr/lib/${DEB_HOST_MULTIARCH}/mesa-egl/ld.so.conf 500 \

  # ldconfig needs to be run immediately as we're changing /etc/ld.so.conf.d/ with
  # alternatives.
  LDCONFIG_NOTRIGGER=y ldconfig

esac

#DEBHELPER#

exit 0

prerm example

set -e

THIS_PACKAGE=libegl1-mesa
THIS_SCRIPT=prerm

case "$1" in
  remove)
  # Use alternatives to make it easier to switch between Mesa and 3rd party modules
  update-alternatives --remove ${DEB_HOST_MULTIARCH}_egl_conf /usr/lib/${DEB_HOST_MULTIARCH}/mesa-egl/ld.so.conf

  # explicit ldconfig due to alternatives
  ldconfig

esac

#DEBHELPER#

exit 0

Summary

• A vendor's libraries must be installed into a private library path. This will typically be of the form /usr/lib/$VENDOR-egl or /usr/lib/$DEB_HOST_MULTIARCH/$VENDOR-egl.

• The vendor packages must include an ld.so.conf file in their private library path. This file should consist of a single line of text, containing the private library path as an absolute path. This means the ld.so.conf file will typically contain a path of the form

/usr/lib/$VENDOR-egl

or

/usr/lib/$DEB_HOST_MULTIARCH/$VENDOR-egl

• The vendor packages must add an ${DEB_HOST_MULTIARCH}_EGL_conf alternative to their ld.so.conf snippet in their postinst maintainer script and remove this alternative in their prerm maintainer script. The alternative should be added at a higher priority than the Mesa alternative (which has a priority of 500).

• A package using this alternatives scheme must not Provide: any of the libegl1-x11, libgles1, libgles2 or libopenvg1 virtual packages.

• A vendor's EGL/GL|ES/OpenVG implementation should be contained in a single package. There is no facility for resolving application dependencies to specific packages in a vendor's implementation. If the vendor also ships an Xorg DDX and/or OpenGL implementation, these may all be shipped as a single package. Note however that OpenGL implementations require additional integration work not covered in this document.

Mesa provides the following EGL binary packages:

• libegl1-mesa (containing /usr/lib/$DEB_HOST_MULTIARCH/mesa-egl/libEGL.so.1)

• libegl1-mesa-dev (containing /usr/include/EGL, /usr/include/KHR, and the libEGL.so→libEGL.so.1 symlink.)

• libopenvg1-mesa (containing /usr/lib/$DEB_HOST_MULTIARCH/mesa-egl/libOpenVG.so.1)

• libopenvg1-mesa-dev (containing /usr/include/VG and the libOpenVG.so→libOpenVG.so.1 symlink.)

• libgles1-mesa (containing /usr/lib/$DEB_HOST_MULTIARCH/mesa-egl/libGLESv1_CM.so.1)

• libgles1-mesa-dev (containing /usr/include/GLES and the libGLESv1_CM.so→libGLESv2_CM.so.1 symlink.)

• libgles2-mesa (containing /usr/lib/$DEB_HOST_MULTIARCH/mesa-egl/libGLESv2.so.2)

• libgles2-mesa-dev (containing /usr/include/GLES2 and the libGLESv2.so→libGLESv2.so.2 symlink.)