.. SPDX-FileCopyrightText: 2023 The meson-python developers
..
.. SPDX-License-Identifier: MIT

.. _reference-environment-variables:

*********************
Environment variables
*********************

.. envvar:: ARCHFLAGS

   This environmental variable is used for supporting architecture cross
   compilation on macOS in a way compatible with setuptools_. It is ignored on
   all other platforms. It can be set to ``-arch arm64`` or to ``-arch
   x86_64`` for compiling for the arm64 and the x86_64 architectures
   respectively. Setting this environment variable to any other value is not
   supported.

   The macOS toolchain allows architecture cross compilation passing the
   ``-arch`` flat to the compilers. ``meson-python`` inspects the content of
   this environment variable and synthesizes a Meson `cross build definition
   file`_ with the appropriate content, and passes it to ``meson setup`` via
   the ``--cross-file`` option.

   Support for this environment variable is maintained only for
   compatibility with existing tools, cibuildwheel_ in particular, and
   is not the recommended solution for cross compilation.

.. _setuptools: https://setuptools.pypa.io/en/latest/setuptools.html
.. _cross build definition file: https://mesonbuild.com/Cross-compilation.html
.. _cibuildwheel: https://cibuildwheel.readthedocs.io/en/stable/

.. envvar:: FORCE_COLOR

   Setting this environment variable to any value forces the use of ANSI
   escape sequences to colorize the ``meson-python``'s console output. Setting
   both ``NO_COLOR`` and ``FORCE_COLOR`` environment variables is an error.

.. envvar:: MACOSX_DEPLOYMENT_TARGET

   This environment variables is used of specifying the target macOS platform
   major version to the Xcode development tools.  If this environment variable
   is set, ``meson-python`` will use the specified macOS version for the
   Python wheel platform tag instead than the macOS version of the build
   machine.

   This variable must be set to macOS major versions only: ``10.9`` to
   ``10.15``, ``11``, ``12``, ``13``, ...

   Please note that the macOS versioning changed from macOS 11 onward. For
   macOS 10, the versioning scheme is ``10.$major.$minor``. From macOS 11
   onward, it is ``$major.$minor.$bugfix``. Wheel tags and deployment targets
   are currently designed to specify compatibility only with major version
   number granularity.

   Another way of specifying the target macOS platform is to use the
   ``-mmacosx-version-min`` compile and link flags.  However, it is not
   possible for ``meson-python`` to detect this, and it will not set the
   Python wheel platform tag accordingly.

.. envvar:: MESONPY_EDITABLE_VERBOSE

   Setting this environment variable to any value enables directing to the
   console the messages emitted during project rebuild triggered by imports of
   editable wheels generated by ``meson-python``. Refer to the
   :ref:`how-to-guides-editable-installs` guide for more information.

.. envvar:: NINJA

   Specify the ninja_ executable to use. It can also be used to select
   ninja_ alternatives like samurai_.

.. _ninja: https://ninja-build.org
.. _samurai: https://github.com/michaelforney/samurai

.. envvar:: NO_COLOR

   Setting this environment variable to any value disables the use of ANSI
   terminal escape sequences to colorize ``meson-python``'s console
   output. Setting both ``NO_COLOR`` and ``FORCE_COLOR`` environment variables
   is an error.
