From 667c9c418e2c20c20442cdfac13f63c859881f6a Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Fri, 10 Mar 2023 18:18:16 +0000 Subject: [PATCH 1/2] DOC: add details on default build options used by meson-python This follows up on the `n_debug` default added in gh-325, documents all other default options and they are used, as well as improves the page on using `pyproject.toml` settings. --- docs/explanations/default-options.rst | 64 +++++++++++++++++++++++++++ docs/index.rst | 1 + docs/reference/pyproject-settings.rst | 10 +++++ 3 files changed, 75 insertions(+) create mode 100644 docs/explanations/default-options.rst diff --git a/docs/explanations/default-options.rst b/docs/explanations/default-options.rst new file mode 100644 index 000000000..9ea14d521 --- /dev/null +++ b/docs/explanations/default-options.rst @@ -0,0 +1,64 @@ +.. SPDX-FileCopyrightText: 2023 The meson-python developers +.. +.. SPDX-License-Identifier: MIT + +.. _explanations-default-options: + +********************* +Default build options +********************* + +Meson offers many `built-in options `__, +and in the vast majority of cases those have good defaults. There are a couple +of cases however where ``meson-python`` either needs to or chooses to override +those with its own defaults. To view what those are for the version of +``meson-python`` you have installed, look at the *User defined options* section +of the output during the configure stage of the build (e.g., by running +``python -m build --wheel``). This will look something like: + +.. code-block:: text + + User defined options + Native files : /home/username/code/project/.mesonpy-native-file.ini + debug : false + optimization : 2 + prefix : /home/username/mambaforge/envs/project-dev + python.platlibdir: /home/username/mambaforge/envs/project-dev/lib/python3.10/site-packages + python.purelibdir: /home/username/mambaforge/envs/project-dev/lib/python3.10/site-packages + b_ndebug : if-release + +Let's go through each option and why they are used: + +- meson-python uses a native file, written to the build dir and named + ``mesonpy-native-file.ini``, in order to point Meson at the correct + ``python`` interpreter to use (the same one for which ``meson-python`` was + installed). This is necessary, because Meson may otherwise look for the first + Python interpreter on the PATH (usually the same one, but not always the + case). Users may use ``--native-file`` to pass a second native file to Meson; + Meson will merge contents of both native file, so as long as the + user-provided file does not try to pass a different path for the ``python`` + binary, this will work without a conflict. +- The ``prefix`` and ``platlibdir``/``purelibdir`` options also point Meson at + that same interpreter and the environment in which it is installed. +- The ``debug``, ``optimization`` and ``b_ndebug`` options are overridden, + because Meson defaults to values that are appropriate for development, while + the main purpose of meson-python is to build release artifacts. + +It is possible to override these defaults, either permanently in your project +or at build time. For example, to build a wheel with debug symbols, use: + +.. code-block:: console + + $ python -m build -Csetup-args=-Ddebug=true + +And to override all debug and optimization settings permanently, add this to +your ``pyproject.toml`` file: + +.. code-block:: toml + + [tool.meson-python.args] + setup = ['-Ddebug=true', '-Doptimization=0', '-Db_ndebug=false'] + +For more details on overriding build options at build time see the +:ref:`reference-config-settings` page, and in ``pyproject.toml`` see the +:ref:`reference-pyproject-settings` page. diff --git a/docs/index.rst b/docs/index.rst index 588f8a514..d72989319 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -135,6 +135,7 @@ Contributors :hidden: explanations/design + explanations/default-options explanations/internal-dependencies explanations/editable-installs diff --git a/docs/reference/pyproject-settings.rst b/docs/reference/pyproject-settings.rst index 1c6b5aa9a..244d89b40 100644 --- a/docs/reference/pyproject-settings.rst +++ b/docs/reference/pyproject-settings.rst @@ -31,3 +31,13 @@ This page lists the configuration settings supported by ``meson-python`` in the * - ``tool.meson-python.args.install`` - Extra arguments to be passed to the ``meson install`` command. + +Usage example: + +.. code-block:: toml + + [tool.meson-python.args] + setup = ['-Dwarning_level=2', '-Db_pie=true'] + dist = ['--include-subprojects'] + compile = ['-j4'] + install = ['--quiet'] From cb1c86cd10b51f1f9d776be6ed029614cf149bf0 Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Tue, 21 Mar 2023 20:24:42 +0000 Subject: [PATCH 2/2] DOC: remove examples in favor of linking to the meson-args page [skip cirrus] --- docs/explanations/default-options.rst | 21 +++------------------ 1 file changed, 3 insertions(+), 18 deletions(-) diff --git a/docs/explanations/default-options.rst b/docs/explanations/default-options.rst index 9ea14d521..f04e39fe7 100644 --- a/docs/explanations/default-options.rst +++ b/docs/explanations/default-options.rst @@ -44,21 +44,6 @@ Let's go through each option and why they are used: because Meson defaults to values that are appropriate for development, while the main purpose of meson-python is to build release artifacts. -It is possible to override these defaults, either permanently in your project -or at build time. For example, to build a wheel with debug symbols, use: - -.. code-block:: console - - $ python -m build -Csetup-args=-Ddebug=true - -And to override all debug and optimization settings permanently, add this to -your ``pyproject.toml`` file: - -.. code-block:: toml - - [tool.meson-python.args] - setup = ['-Ddebug=true', '-Doptimization=0', '-Db_ndebug=false'] - -For more details on overriding build options at build time see the -:ref:`reference-config-settings` page, and in ``pyproject.toml`` see the -:ref:`reference-pyproject-settings` page. +It is possible to override these defaults, either permanently in your +``pyproject.toml`` or at build time via the build frontend CLI. +See the :ref:`how-to-guides-meson-args` page for examples of both methods.