From: Jason Ekstrand Date: Fri, 9 Jul 2021 17:52:55 +0000 (-0500) Subject: docs: Add docs for running a local Mesa build X-Git-Tag: upstream/21.2.3~559 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=81670a47f0832b0aed787d8487c4b26234e5028f;p=platform%2Fupstream%2Fmesa.git docs: Add docs for running a local Mesa build I'm tired of explaining this to people. Let's put it in the actual project docs. Reviewed-by: Chia-I Wu Part-of: --- diff --git a/docs/install.rst b/docs/install.rst index 69f1dea..ca14e6f 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -101,12 +101,98 @@ On Windows you can also use the Visual Studio backend Please read the :doc:`detailed meson instructions ` for more information -3. Building with AOSP (Android) +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) ------------------------------- -4. Library Information +5. Library Information ---------------------- When compilation has finished, look in the top-level ``lib/`` (or @@ -137,7 +223,7 @@ If you built the DRI hardware drivers, you'll also see the DRI drivers: If you built with Gallium support, look in lib/gallium/ for Gallium-based versions of libGL and device drivers. -5. Building OpenGL programs with pkg-config +6. Building OpenGL programs with pkg-config ------------------------------------------- Running ``ninja install`` will install package configuration files for