@@ -19,7 +19,7 @@ the ``-C`` short command line option:
1919
2020.. tab-set ::
2121
22- .. tab-item :: pypa/buid
22+ .. tab-item :: pypa/build
2323 :sync: key_pypa_build
2424
2525 .. code-block :: console
@@ -59,3 +59,63 @@ immediately install it, replace ``wheel`` with ``install``. See the
5959
6060.. _build : https://pypa-build.readthedocs.io/en/stable/
6161.. _pip : https://pip.pypa.io/
62+
63+
64+ Using a persistent build directory
65+ ==================================
66+
67+ By default, ``meson-python `` will create a temporary build directory, which
68+ gets cleaned up after the sdist or wheel has been built, or if the build fails.
69+ The ``build-dir `` config seting (see :ref: `reference-config-settings `) can be
70+ used to build in a user-specified build directory instead. For example:
71+
72+ .. tab-set ::
73+
74+ .. tab-item :: pypa/build
75+ :sync: key_pypa_build
76+
77+ .. code-block :: console
78+
79+ $ python -m build -Cbuild-dir=build
80+
81+ tab-item :: pip
82+ :sync: key_pip
83+
84+ .. code-block :: console
85+
86+ $ python -m pip install . -Cbuild-dir=build
87+
88+
89+ build `` directory will now contain all the build output created by
90+ ``meson ``, ``ninja `` and ``meson-python ``. This may be useful for a couple of
91+ reasons:
92+
93+ - For development efficiency (incremental builds)
94+ - For accessing build logs and intermediate build outputs when debugging
95+
96+ The same build directory can be used by subsequent invocations of
97+ ``meson-python ``. This avoids having to rebuild the whole project when testing
98+ changes during development. This will work with any config settings flags,
99+ including for cross compilation. The one thing to keep in mind is that changing
100+ the version of ``meson `` or ``meson-python `` in the build environment between
101+ separate builds in the same build directory is not supported (it often works,
102+ but may fail - and the error message cannot be guaranteed to be clear about the
103+ reason).
104+
105+ Using ``build-dir `` makes it possible to access the log files that Meson
106+ creates. When a build fails, Meson's CLI logging will display the reason for
107+ the failure in most cases. However, it is sometimes necessary to look at more
108+ detailed logs like ``meson-logs/meson-log.txt ``. A common reason for this is
109+ when Meson's dependency detection fails: it is often necessary to look at the
110+ detailed output of ``pkg-config `` or other dependency detection methods to
111+ understand why the detection failed. This is particularly common in CI setups -
112+ it can be helpful to show more detailed log files when the build step of a CI
113+ build fails, for example in a GitHub Actions workflow file:
114+
115+ .. code-block :: yaml
116+
117+ - name : Build the package
118+ run : python -m build --wheel -Cbuild-dir=build
119+ - name : Show meson-log.txt
120+ if : failure() # or `always()`, if output is not too long
121+ run : cat build/meson-logs/meson-log.txt
0 commit comments