mirror of
https://gitlab.freedesktop.org/mesa/mesa.git
synced 2024-11-27 12:14:10 +08:00
81670a47f0
I'm tired of explaining this to people. Let's put it in the actual project docs. Reviewed-by: Chia-I Wu <olvaffe@gmail.com> Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/11809>
240 lines
7.4 KiB
ReStructuredText
240 lines
7.4 KiB
ReStructuredText
Compiling and Installing
|
|
========================
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
:hidden:
|
|
|
|
meson
|
|
|
|
1. Prerequisites for building
|
|
-----------------------------
|
|
|
|
1.1 General
|
|
~~~~~~~~~~~
|
|
|
|
Build system
|
|
^^^^^^^^^^^^
|
|
|
|
- `Meson <https://mesonbuild.com>`__ is required when building on \*nix
|
|
platforms and on Windows.
|
|
- Android Build system when building as native Android component. Meson
|
|
is used when building ARC.
|
|
|
|
Compiler
|
|
^^^^^^^^
|
|
|
|
The following compilers are known to work, if you know of others or
|
|
you're willing to maintain support for other compiler get in touch.
|
|
|
|
- GCC 4.2.0 or later (some parts of Mesa may require later versions)
|
|
- Clang - exact minimum requirement is currently unknown.
|
|
- Microsoft Visual Studio 2015 or later is required, for building on
|
|
Windows.
|
|
|
|
Third party/extra tools.
|
|
^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
- `Python <https://www.python.org/>`__ - Python 3.5 or newer is required.
|
|
- `Python Mako module <http://www.makotemplates.org/>`__ - Python Mako
|
|
module is required. Version 0.8.0 or later should work.
|
|
- Lex / Yacc - for building the Mesa IR and GLSL compiler.
|
|
|
|
On Linux systems, Flex and Bison versions 2.5.35 and 2.4.1,
|
|
respectively, (or later) should work. On Windows with MinGW, install
|
|
Flex and Bison with:
|
|
|
|
.. code-block:: console
|
|
|
|
mingw-get install msys-flex msys-bison
|
|
|
|
For MSVC on Windows, install `Win
|
|
flex-bison <http://winflexbison.sourceforge.net/>`__.
|
|
|
|
.. note::
|
|
|
|
Some versions can be buggy (e.g. Flex 2.6.2) so do try others
|
|
if things fail.
|
|
|
|
1.2 Requirements
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
The requirements depends on the features selected at configure stage.
|
|
Check/install the respective development package as prompted by the
|
|
configure error message.
|
|
|
|
Here are some common ways to retrieve most/all of the dependencies based
|
|
on the packaging tool used by your distro.
|
|
|
|
.. code-block:: console
|
|
|
|
zypper source-install --build-deps-only Mesa # openSUSE/SLED/SLES
|
|
yum-builddep mesa # yum Fedora, OpenSuse(?)
|
|
dnf builddep mesa # dnf Fedora
|
|
apt-get build-dep mesa # Debian and derivatives
|
|
... # others
|
|
|
|
2. Building with meson
|
|
----------------------
|
|
|
|
**Meson >= 0.46.0 is required**
|
|
|
|
Meson is the latest build system in mesa, it is currently able to build
|
|
for \*nix systems like Linux and BSD, macOS, Haiku, and Windows.
|
|
|
|
The general approach is:
|
|
|
|
.. code-block:: console
|
|
|
|
meson builddir/
|
|
ninja -C builddir/
|
|
sudo ninja -C builddir/ install
|
|
|
|
On Windows you can also use the Visual Studio backend
|
|
|
|
.. code-block:: console
|
|
|
|
meson builddir --backend=vs
|
|
cd builddir
|
|
msbuild mesa.sln /m
|
|
|
|
Please read the :doc:`detailed meson instructions <meson>` for more
|
|
information
|
|
|
|
3. Running against a local build
|
|
--------------------------------
|
|
|
|
It's often necessary or useful when debugging driver issues or testing new
|
|
branches to run against a local build of Mesa without doing a system-wide
|
|
install. To do this, choose a temporary location for the install. A directory
|
|
called ``installdir`` inside your mesa tree is as good as anything. All of the
|
|
commands below will assume ``$MESA_INSTALLDIR`` is an absolute path to this
|
|
location.
|
|
|
|
First, configure Mesa and install in the temporary location:
|
|
|
|
.. code-block:: console
|
|
|
|
meson builddir/ -Dprefix="$MESA_INSTALLDIR" OTHER_OPTIONS
|
|
ninja -C builddir/ install
|
|
|
|
where ``OTHER_OPTIONS`` is replaced by any meson configuration options you may
|
|
want. For instance, if you want to build the LLVMpipe drivers, it would look
|
|
like this:
|
|
|
|
.. code-block:: console
|
|
|
|
meson builddir/ -Dprefix="$MESA_INSTALLDIR" -Ddri-drivers= \
|
|
-Dgallium-drivers=swrast -Dvulkan-drivers=swrast
|
|
ninja -C builddir/ install
|
|
|
|
Once Mesa has built and installed to ``$MESA_INSTALLDIR``, you can run any app
|
|
against your temporary install by setting the right environment variables.
|
|
Which variable you have to set depends on the API.
|
|
|
|
OpenGL
|
|
~~~~~~
|
|
|
|
.. code-block:: console
|
|
|
|
LD_LIBRARY_PATH="$MESA_INSTALLDIR/lib64" glxinfo
|
|
|
|
You may need to use ``lib`` instead of ``lib64`` on some systems or a full
|
|
library specifier on debian. Look inside ``installdir`` for the directory that
|
|
contains ``libGL.so`` and use that one.
|
|
|
|
Vulkan
|
|
~~~~~~
|
|
|
|
.. code-block:: console
|
|
|
|
VK_ICD_FILENAMES="$MESA_INSTALLDIR/share/vulkan/icd/my_icd.json" vulkaninfo
|
|
|
|
where ``my_icd.json`` is replaced with the actual ICD json file name. This
|
|
will depend on your driver. For instance, the 64-bit lavapipe driver ICD file
|
|
is named ``lvp_icd.x86_64.json``.
|
|
|
|
OpenCL
|
|
~~~~~~
|
|
|
|
.. code-block:: console
|
|
|
|
OCL_ICD_VENDORS="$MESA_INSTALLDIR/etc/OpenCL/vendors" clinfo
|
|
|
|
Unlike Vulkan, OpenCL takes a path to the whole ``vendors`` folder and will
|
|
enumerate any drivers found there.
|
|
|
|
Troubleshooting local builds
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
If you are trying to run an app against a local build and it's not working,
|
|
here are a few things to check:
|
|
|
|
1. Double-check your paths and try with the simplest app you can. Before
|
|
banging your head on a Steam game, make sure your path works with
|
|
``glxgears`` first.
|
|
|
|
2. Watch out for wrapper scripts. Some more complex apps such as games have
|
|
big start-up scripts. Sometimes those scripts scrub the environment or set
|
|
``LD_LIBRARY_PATH`` to something in the game's install directory.
|
|
|
|
3. Is your Mesa build the same arch as your app? Lots of games are still
|
|
32-bit and your Mesa build is probably 64-bit by default.
|
|
|
|
4. 32 and 64-bit builds in the same local install directory doesn't typically
|
|
work. Distros go to great lengths to make this work in your system install
|
|
and it's hard to get it right for a local install. If you've recently
|
|
built 64-bit and are now building 32-bit, throw away the install directory
|
|
first to prevent conflicts.
|
|
|
|
4. Building with AOSP (Android)
|
|
-------------------------------
|
|
|
|
<TODO>
|
|
|
|
5. Library Information
|
|
----------------------
|
|
|
|
When compilation has finished, look in the top-level ``lib/`` (or
|
|
``lib64/``) directory. You'll see a set of library files similar to
|
|
this:
|
|
|
|
.. code-block:: console
|
|
|
|
lrwxrwxrwx 1 brian users 10 Mar 26 07:53 libGL.so -> libGL.so.1*
|
|
lrwxrwxrwx 1 brian users 19 Mar 26 07:53 libGL.so.1 -> libGL.so.1.5.060100*
|
|
-rwxr-xr-x 1 brian users 3375861 Mar 26 07:53 libGL.so.1.5.060100*
|
|
lrwxrwxrwx 1 brian users 14 Mar 26 07:53 libOSMesa.so -> libOSMesa.so.6*
|
|
lrwxrwxrwx 1 brian users 23 Mar 26 07:53 libOSMesa.so.6 -> libOSMesa.so.6.1.060100*
|
|
-rwxr-xr-x 1 brian users 23871 Mar 26 07:53 libOSMesa.so.6.1.060100*
|
|
|
|
**libGL** is the main OpenGL library (i.e. Mesa), while **libOSMesa** is
|
|
the OSMesa (Off-Screen) interface library.
|
|
|
|
If you built the DRI hardware drivers, you'll also see the DRI drivers:
|
|
|
|
.. code-block:: console
|
|
|
|
-rwxr-xr-x 1 brian users 16895413 Jul 21 12:11 i915_dri.so
|
|
-rwxr-xr-x 1 brian users 16895413 Jul 21 12:11 i965_dri.so
|
|
-rwxr-xr-x 1 brian users 11849858 Jul 21 12:12 r200_dri.so
|
|
-rwxr-xr-x 1 brian users 11757388 Jul 21 12:12 radeon_dri.so
|
|
|
|
If you built with Gallium support, look in lib/gallium/ for
|
|
Gallium-based versions of libGL and device drivers.
|
|
|
|
6. Building OpenGL programs with pkg-config
|
|
-------------------------------------------
|
|
|
|
Running ``ninja install`` will install package configuration files for
|
|
the pkg-config utility.
|
|
|
|
When compiling your OpenGL application you can use pkg-config to
|
|
determine the proper compiler and linker flags.
|
|
|
|
For example, compiling and linking a GLUT application can be done with:
|
|
|
|
.. code-block:: console
|
|
|
|
gcc `pkg-config --cflags --libs glut` mydemo.c -o mydemo
|