From bc17ac58661c2dbbd5fea48d4af628baef434e86 Mon Sep 17 00:00:00 2001 From: Dylan Baker Date: Tue, 17 Oct 2017 12:19:49 -0700 Subject: [PATCH] docs: add documentation for building with meson v2: - Add information about CC, CXX, CFLAGS, and CXXFLAGS (Nicolai) - Add message at top that meson for mesa is still a work in progress - Add trailing "/" to directories (Eric E.) - Fix a number of spelling/grammar/style suggestions from Eric E. - Make a number of changes as suggested by Emil. v3: - Fix order of commands in example (Eric E.) - Add documentation for overriding LLVM version (Eric E.) v4: - Rebase on master - update default buildtype - add note about b_ndebug - Clarify meson configure a bit v5: - use for command line arguments (Eric E.) - Add note about listing options without a build directory - Minor formatting changes (Eric E.) - Replace the CC, CFLAGS, etc section with an environment variables section, which mentions CC, CXX, CFLAGS, CXXFLAGS, LDFLAGS, and DESTDIR - Add comment that not using buildtype debug might make debugging harder - Add comment that b_ndebug and buildtype are orthogonal Signed-off-by: Dylan Baker Reviewed-by: Eric Engestrom (v3) --- docs/contents.html | 1 + docs/meson.html | 168 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 169 insertions(+) create mode 100644 docs/meson.html diff --git a/docs/contents.html b/docs/contents.html index d545542..9a86019 100644 --- a/docs/contents.html +++ b/docs/contents.html @@ -43,6 +43,7 @@
  • Compiling / Installing
  • Precompiled Libraries diff --git a/docs/meson.html b/docs/meson.html new file mode 100644 index 0000000..77f89b0 --- /dev/null +++ b/docs/meson.html @@ -0,0 +1,168 @@ + + + + + Compilation and Installation using Meson + + + + +
    +

    The Mesa 3D Graphics Library

    +
    + + +
    + +

    Compilation and Installation using Meson

    + +

    1. Basic Usage

    + +

    The Meson build system for Mesa is still under active development, +and should not be used in production environments.

    + +

    The meson build is currently only tested on linux, and is known to not work +on macOS, Windows, and haiku. This will be fixed.

    + +

    +The meson program is used to configure the source directory and generates +either a ninja build file or Visual Studio® build files. The latter must +be enabled via the --backend switch, as ninja is the default backend on all +operating systems. Meson only supports out-of-tree builds, and must be passed a +directory to put built and generated sources into. We'll call that directory +"build" for examples. +

    + +
    +    meson build/
+
    + +

    +To see a description of your options you can run meson configure +along with a build directory to view the selected options for. This will show +your meson global arguments and project arguments, along with their defaults +and your local settings. + +Moes does not currently support listing options before configure a build +directory, but this feature is being discussed upstream. +

    + +
    +    meson configure build/
+
    + +

    +With additional arguments meson configure is used to change +options on already configured build directory. All options passed to this +command are in the form -D "command"="value". +

    + +
    +    meson configure build/ -Dprefix=/tmp/install -Dglx=true
+
    + +

    +Once you've run the initial meson command successfully you can use +your configured backend to build the project. With ninja, the -C option can be +be used to point at a directory to build. +

    + +
    +    ninja -C build/
+
    + +

    +Without arguments, it will produce libGL.so and/or several other libraries +depending on the options you have chosen. Later, if you want to rebuild for a +different configuration, you should run ninja clean before +changing the configuration, or create a new out of tree build directory for +each configuration you want to build. + +http://mesonbuild.com/Using-multiple-build-directories.html +

    + +
    Environment Variables
    +

    Meson supports the standard CC and CXX envrionment variables for +changing the default compiler, and CFLAGS, CXXFLAGS, and LDFLAGS for setting +options to the compiler and linker. + +The default compilers depends on your operating system. Meson supports most of +the popular compilers, a complete list is available +here. + +These arguments are consumed and stored by meson when it is initialized or +re-initialized. Therefore passing them to meson configure will not do anything, +and passing them to ninja will only do something if ninja decides to +re-initialze meson, for example, if a meson.build file has been changed. +Changing these variables will not cause all targets to be rebuilt, so running +ninja clean is recomended when changing CFLAGS or CXXFLAGS. meson will never +change compiler in a configured build directory. +

    + +
    +    CC=clang CXX=clang++ meson build-clang
+    ninja -C build-clang
+    ninja -C build-clang clean
+    touch meson.build
+    CFLAGS=-Wno-typedef-redefinition ninja -C build-clang
+
    + +

    Meson also honors DESTDIR for installs

    +
    + + +
    LLVM
    +

    Meson includes upstream logic to wrap llvm-config using it's standard +dependncy interface. It will search $PATH (or %PATH% on windows) for +llvm-config, so using an LLVM from a non-standard path is as easy as +PATH=/path/with/llvm-config:$PATH meson build. +

    + + +
    PKG_CONFIG_PATH
    +

    The +pkg-config utility is a hard requirement for configuring and +building Mesa on Linux and *BSD. It is used to search for external libraries +on the system. This environment variable is used to control the search +path for pkg-config. For instance, setting +PKG_CONFIG_PATH=/usr/X11R6/lib/pkgconfig will search for +package metadata in /usr/X11R6 before the standard +directories.

    +
    + + +

    +One of the oddities of meson is that some options are different when passed to +the meson than to meson configure. These options are +passed as --option=foo to meson, but -Doption=foo to meson +configure. Mesa defined options are always passed as -Doption=foo. +

    + +

    For those coming from autotools be aware of the following:

    + +
    +
    --buildtype/-Dbuildtype
    +

    This option will set the compiler debug/optimisation levels to aid +debugging the Mesa libraries.

    + +

    Note that in meson this defaults to "debugoptimized", and not setting it to +"release" will yield non-optimal performance and binary size. Not using "debug" +may interfer with debbugging as some code and validation will be optimized +away. +

    + +

    For those wishing to pass their own -O option, use the "plain" buildtype, +which cuases meson to inject no additional compiler arguments, only those in +the C/CXXFLAGS and those that mesa itself defines.

    +
    +
    + +
    +
    -Db_ndebug
    +

    This option controls assertions in meson projects. When set to false +(the default) assertions are enabled, when set to true they are disabled. This +is unrelated to the buildtype; setting the latter to +release will not turn off assertions. +

    +
    +
    -- 2.7.4