### Example Meson Build Options Output

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/explanations/default-options.rst

This text output shows an example of how user-defined options are summarized during the 'meson setup' stage. It illustrates the native files used, build type, NDEBUG setting, and Visual Studio runtime.

```text
User defined options
  Native files: $builddir/meson-python-native-file.ini
  buildtype   : release
  b_ndebug    : if-release
  b_vscrt     : md
```

--------------------------------

### Install Documentation Tools

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/how-to-guides/contributing.rst

Installs the necessary tools for building and working with the project's documentation.

```console
$ uv pip install --group docs
```

--------------------------------

### Set up Development Environment

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/how-to-guides/contributing.rst

Installs development and testing dependencies using uv. Ensures the project is installed in editable mode.

```console
$ uv venv
$ source .venv/bin/activate
$ uv pip install meson ninja pyproject-metadata
$ uv pip install --no-build-isolation --editable .
$ uv pip install --group test
$ uv pip install ruff mypy
```

--------------------------------

### Install Project from PyPI

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/tutorials/introduction.rst

After uploading your package, it can be installed by users using `pip`. This command fetches and installs the latest version of your project.

```console
pip install our-first-project
```

--------------------------------

### Install and Run Build Tool

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/tutorials/introduction.rst

Install the `build` tool and use it to generate distribution artifacts for your project. This process creates both an sdist and a wheel by default.

```console
pip install build
python -m build
```

--------------------------------

### Select Install Targets via Build Arguments (pypa/build)

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/how-to-guides/meson-args.rst

Temporarily select installation tags for the wheel build using the -Cinstall-args option with pypa/build.

```console
$ python -m build --wheel -Cinstall-args="--tags=runtime,python-runtime" .
```

--------------------------------

### Select Install Targets via Build Arguments (pip)

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/how-to-guides/meson-args.rst

Temporarily select installation tags for the wheel build using the -Cinstall-args option with pip.

```console
$ python -m pip wheel -Cinstall-args="--tags=runtime,python-runtime" .
```

--------------------------------

### Select Install Targets in pyproject.toml

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/how-to-guides/meson-args.rst

Specify installation tags in pyproject.toml to include only specific targets in the Python wheel during the install phase.

```toml
[tool.meson-python.args]
install = ['--tags=runtime,python-runtime']
```

--------------------------------

### Install Build Dependencies

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/how-to-guides/editable-installs.rst

Install the necessary build dependencies, including meson-python, meson, and ninja, to ensure compiled components can be rebuilt on import.

```console
$ python -m pip install meson-python meson ninja
```

--------------------------------

### Install and Test the Python Package

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/tutorials/introduction.rst

Installs the local Python package using pip and verifies the installation by listing packages and importing the custom module in the Python interpreter.

```console
$ pip install .
$ pip list
...
our-first-project   0.0.1
...

$ python
>>> import our_first_module
>>> our_first_module.foo()
'bar'
```

--------------------------------

### Build an internal shared library

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/how-to-guides/shared-libraries.rst

Use `shared_library()` to build a shared library. Set `install: true` to install it to the default system location (`libdir`).

```meson
example_lib = shared_library(
    'example',
    'examplelib.c',
    install: true,
)
```

--------------------------------

### Install and Upload with Twine

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/tutorials/introduction.rst

Install the `twine` tool to upload your built distribution artifacts to a package repository like PyPI. Ensure you have built your artifacts first.

```console
pip install twine
twine upload dist/*
```

--------------------------------

### Install Target

Source: https://github.com/mesonbuild/meson-python/blob/main/tests/packages/cmake-subproject/subprojects/cmaketest/CMakeLists.txt

Installs the 'cmaketest' target. This makes the library available for use by other projects or for deployment.

```cmake
install(TARGETS cmaketest)
```

--------------------------------

### Enable Verbose Mode for Editable Installs

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/how-to-guides/editable-installs.rst

Illustrates how to enable verbose mode during an editable installation using pip. This is useful for inspecting the build process output when a package is rebuilt on import.

```console
python -m pip install --no-build-isolation -Ceditable-verbose=true --editable .
```

--------------------------------

### Set Default Library to Static in pyproject.toml

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/how-to-guides/meson-args.rst

Configure Meson to use static libraries by default for binary wheels by adding the --default-library=static argument to the setup command in pyproject.toml.

```toml
[tool.meson-python.args]
setup = ['--default-library=static']
```

--------------------------------

### Configure Meson Build for Python Extension

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/tutorials/introduction.rst

Sets up the Meson build system to compile a C extension module for Python. Ensures the module is installed.

```meson
project('purelib-and-platlib', 'c')

py = import('python').find_installation(pure: false)

py.extension_module(
    'our_first_module',
    'our_first_module.c',
    install: true,
)
```

--------------------------------

### Install Package in Editable Mode

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/how-to-guides/editable-installs.rst

Use this command to install the current project in editable mode. It's recommended to disable build isolation and ensure build dependencies are met.

```console
$ python -m pip install --no-build-isolation --editable .
```

--------------------------------

### Set Build Optimization Level in pyproject.toml

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/how-to-guides/meson-args.rst

Configure the build optimization level by passing the -Doptimization argument to the meson setup command in pyproject.toml.

```toml
[tool.meson-python.args]
```

--------------------------------

### Create a C Extension Module

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/tutorials/introduction.rst

Defines a simple Python module 'our_first_module' with a 'foo' function that returns the string 'bar'. This is a native module example.

```c
#include <Python.h>

static PyObject* foo(PyObject* self)
{
    return PyUnicode_FromString("bar");
}

static PyMethodDef methods[] = {
    {"foo", (PyCFunction)foo, METH_NOARGS, NULL},
    {NULL, NULL, 0, NULL},
};

static struct PyModuleDef module = {
    PyModuleDef_HEAD_INIT,
    "our_first_module",
    NULL,
    -1,
    methods,
};

PyMODINIT_FUNC PyInit_our_first_module(void)
{
    return PyModule_Create(&module);
}
```

--------------------------------

### Install Editable Debug Build

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/how-to-guides/debug-builds.rst

Use this command to install your package in editable mode with a debug build type and a fixed build directory. This ensures shared libraries contain correct paths for debugging.

```console
pip install -e . --no-build-isolation \
    -Csetup-args=-Dbuildtype=debug \
    -Cbuild-dir=build-dbg
```

--------------------------------

### Install internal shared library to site-packages

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/how-to-guides/shared-libraries.rst

To make a shared library available within a Python package, set `install_dir` to a path within the package's install tree, like `py.get_install_dir() / 'mypkg/subdir'`. This ensures portable linking.

```meson
example_lib = shared_library(
    'example',
    'examplelib.c',
    install: true,
    install_dir: py.get_install_dir() / 'mypkg/subdir',
)
```

--------------------------------

### Configure Static Library Build in pyproject.toml

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/how-to-guides/shared-libraries.rst

Use this configuration in pyproject.toml to ensure library targets are built as static and subprojects are skipped during installation. This simplifies RPATH and DLL search path management.

```toml
[tool.meson-python.args]
setup = ['--default-library=static']
install = ['--skip-subprojects']
```

--------------------------------

### Link Static Library from Meson Subproject

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/how-to-guides/shared-libraries.rst

Example of how to link against a static library from a Meson subproject named 'bar' in your meson.build file. This assumes the subproject exposes its library via a dependency named 'bar_dep'.

```meson
bar_proj = subproject('bar')
bar_dep = bar_proj.get_variable('bar_dep')

py.extension_module(

```

--------------------------------

### Force MSVC Compilers Permanently

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/how-to-guides/meson-args.rst

Configure Meson to permanently use MSVC compilers on Windows by adding '--vsenv' to the setup arguments in 'pyproject.toml'.

```toml
[tool.meson-python.args]
setup = ['--vsenv']
```

--------------------------------

### Accessing Data Files in Python Packages

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/how-to-guides/editable-installs.rst

Demonstrates the incorrect method of accessing data files using `__file__` and `pathlib`. This approach fails when modules are loaded via special loaders, such as in editable installs.

```python
import pathlib

data = pathlib.Path(__file__).parent.joinpath('data.txt').read_text()
uuid = pathlib.Path(__file__).parent.joinpath('uuid.txt').read_text()  # WRONG!
```

--------------------------------

### Link extension module against internal shared library

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/how-to-guides/shared-libraries.rst

Use `link_with` to link an extension module against a shared library. Set `install_rpath: '$ORIGIN'` to ensure the extension can find the library when installed in the same directory.

```meson
py.extension_module('_extmodule',
    '_extmodule.c',
    link_with: example_lib,
    install: true,
    subdir: 'mypkg/subdir',
    install_rpath: '$ORIGIN'
)
```

--------------------------------

### Exclude Files from Source Distribution with Git

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/how-to-guides/sdist.rst

Use the 'export-ignore' attribute in a .gitattributes file to exclude specific files or directories from the source distribution when using Git. This example excludes the 'dev' folder.

```none
dev/** export-ignore
```

--------------------------------

### Declare Meson Version Requirement in pyproject.toml

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/reference/meson-compatibility.rst

When a package relies on Meson features specific to a certain version, explicitly declare the Meson version requirement in pyproject.toml. This ensures the correct Meson version is installed in the isolated build environment.

```toml
[build-system]
build-backend = 'mesonpy'
requires = [
  'meson-python',
  'meson >= 1.1.0',
]

```

--------------------------------

### Build Source Distribution

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/how-to-guides/sdist.rst

Execute this command in the project root to create a .tar.gz archive in the dist folder. This archive contains the latest commit's content, excluding metadata, uncommitted modifications, and unknown files.

```console
$ python -m build --sdist .
```

--------------------------------

### Generate and Inspect Documentation

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/how-to-guides/contributing.rst

Builds the HTML documentation using Sphinx and opens the index file in the default web browser.

```console
$ python -m sphinx docs html
$ open html/index.html
```

--------------------------------

### Configure Subproject with Options

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/how-to-guides/shared-libraries.rst

Pass configuration options to a subproject during its initialization. This is useful for disabling specific components like documentation.

```meson
foo_subproj = subproject('foo',
default_options: {
    'docs': 'disabled',
})
foo_dep = foo_subproj.get_variable('foo_dep')
```

--------------------------------

### Configure Build System in pyproject.toml

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/index.rst

Specify meson-python as the build backend in pyproject.toml to enable pip or build to create sdists or wheels.

```toml
[build-system]
build-backend = 'mesonpy'
requires = ['meson-python']

```

--------------------------------

### Specify build config settings with pypa/build

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/how-to-guides/config-settings.rst

Use the `-C` option to pass configuration settings to `pypa/build`. Multiple settings can be passed by repeating the option.

```console
$ python -m build --wheel \
      -Csetup-args="-Doption=true" \
      -Csetup-args="-Dvalue=1" \
      -Ccompile-args="-j6"
```

--------------------------------

### Configure Build System in pyproject.toml

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/tutorials/introduction.rst

Specifies 'mesonpy' as the build backend and lists 'meson-python' as a build requirement. This configuration is essential for Python packaging tools.

```toml
[build-system]
build-backend = 'mesonpy'
requires = ['meson-python']
```

--------------------------------

### Specify build config settings with pip

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/how-to-guides/config-settings.rst

Use the `-C` option to pass configuration settings to `pip`. Multiple settings can be passed by repeating the option.

```console
$ python -m pip wheel . \
      -Csetup-args="-Doption=true" \
      -Csetup-args="-Dvalue=1" \
      -Ccompile-args="-j6"
```

--------------------------------

### Upload Artifacts to PyPI

Source: https://github.com/mesonbuild/meson-python/blob/main/RELEASE.rst

Push the built artifacts to PyPI using 'twine'. GPG signing is not required for PyPI uploads.

```console
$ twine upload dist/*
```

--------------------------------

### Create GPG-signed Git Tag

Source: https://github.com/mesonbuild/meson-python/blob/main/RELEASE.rst

Create a GPG-signed tag for the release. The tag title should follow the 'meson-python X.Y.Z' format, and the tag body should be a plain text version of the change-log for the current release.

```console
$ git tag -s X.Y.Z
```

--------------------------------

### Set Default Library to Static via Build Arguments (pypa/build)

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/how-to-guides/meson-args.rst

Temporarily set the default library type to static during the build process using the -Csetup-args option with pypa/build.

```console
$ python -m build --wheel -Csetup-args="--default-library=static" .
```

--------------------------------

### Configure MSVC for cibuildwheel

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/how-to-guides/meson-args.rst

Set up MSVC compilation for Windows wheels using cibuildwheel by specifying '--vsenv' in the 'config-settings' for Windows builds.

```toml
[tool.cibuildwheel.windows]
config-settings = { setup-args = ["--vsenv"] }
```

--------------------------------

### Set Default Library to Static via Build Arguments (pip)

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/how-to-guides/meson-args.rst

Temporarily set the default library type to static during the build process using the -Csetup-args option with pip.

```console
$ python -m pip wheel -Csetup-args="--default-library=static" .
```

--------------------------------

### Use a persistent build directory with pip

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/how-to-guides/config-settings.rst

Specify a persistent build directory using the `-Cbuild-dir` option with `pip` to retain build artifacts.

```console
$ python -m pip install . -Cbuild-dir=build
```

--------------------------------

### Build Python Artifacts

Source: https://github.com/mesonbuild/meson-python/blob/main/RELEASE.rst

Build the Python artifacts using the 'build' package.

```console
$ python -m build
```

--------------------------------

### Upload to Test PyPI with Twine

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/tutorials/introduction.rst

Use `twine` to upload your distribution artifacts to the Test PyPI repository. This is useful for testing your upload process without affecting the main PyPI index.

```console
twine upload -r testpypi dist/*
```

--------------------------------

### Use a persistent build directory with pypa/build

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/how-to-guides/config-settings.rst

Specify a persistent build directory using the `-Cbuild-dir` option with `pypa/build` to retain build artifacts.

```console
$ python -m build --wheel -Cbuild-dir=build
```

--------------------------------

### Show Meson log on failure in GitHub Actions

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/how-to-guides/config-settings.rst

This GitHub Actions workflow snippet demonstrates how to capture and display the `meson-log.txt` from a persistent build directory when a build fails.

```yaml
- name: Build the package
  run: python -m build --wheel -Cbuild-dir=build
- name: Show meson-log.txt
  if: ${{ failure() }}
  run: cat build/meson-logs/meson-log.txt
```

--------------------------------

### Set Optimization Level Temporarily

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/how-to-guides/meson-args.rst

Pass the optimization level argument to Meson build using 'build' or 'pip'. This is useful for temporary build configurations.

```console
$ python -m build --wheel -Csetup-args="-Doptimization=3" .
```

```console
$ python -m pip wheel -Csetup-args="-Doptimization=3" .
```

--------------------------------

### Push Git Commit and Tag

Source: https://github.com/mesonbuild/meson-python/blob/main/RELEASE.rst

Push the release commit and tag to the repository.

```console
$ git push
$ git push --tags
```

--------------------------------

### CMake Project Configuration

Source: https://github.com/mesonbuild/meson-python/blob/main/tests/packages/cmake-subproject/subprojects/cmaketest/CMakeLists.txt

Sets the minimum required CMake version and names the project. Specifies the C++ standard to be used.

```cmake
cmake_minimum_required(VERSION 3.5)

project(cmaketest)
set(CMAKE_CXX_STANDARD 14)
```

--------------------------------

### Configure Meson Arguments in pyproject.toml

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/how-to-guides/meson-args.rst

Specify arguments for Meson commands permanently in your project's pyproject.toml file.

```toml
[tool.meson-python.args]
setup = ['-Doption=false', '-Dfeature=enabled', '-Dvalue=42']
compile = ['-j4']
install = ['--tags=bindings']
dist = ['--include-subprojects']
```

--------------------------------

### Define Project Metadata in pyproject.toml

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/tutorials/introduction.rst

Defines the core metadata for the Python package, including name, version, description, and Python version requirements. Ensure 'readme' and 'license' files exist.

```toml
...

[project]
name = 'our-first-project'
version = '0.0.1'
description = 'Our first Python project, using meson-python!'
readme = 'README.md'
requires-python = '>=3.8'
license = {file = 'LICENSE.txt'}
authors = [
  {name = 'Bowsette Koopa', email = 'bowsette@example.com'},
]
```

--------------------------------

### Include Directories and Library Definition

Source: https://github.com/mesonbuild/meson-python/blob/main/tests/packages/cmake-subproject/subprojects/cmaketest/CMakeLists.txt

Includes the binary directory for headers and defines a shared C++ library named 'cmaketest' from 'cmaketest.cpp'.

```cmake
include_directories(${CMAKE_CURRENT_BINARY_DIR})

add_library(cmaketest SHARED cmaketest.cpp)
```

--------------------------------

### Python code for shared library loading on Windows

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/how-to-guides/shared-libraries.rst

This Python code snippet demonstrates how to handle internal shared libraries on Windows, which lacks RPATH support. It involves extending the DLL search path or preloading libraries.

```python
import os
import sys


if sys.platform == "win32":
    # On Windows, DLLs are searched for in the current directory, 
    # the system directory and directories listed in the PATH environment variable.
    # We are installing the shared library into the package directory, 
    # so we need to add this directory to the DLL search path.
    package_dir = os.path.dirname(os.path.abspath(__file__))
    os.environ["PATH"] = package_dir + os.pathsep + os.environ["PATH"]


# Import the extension module
from . import _extmodule

```

--------------------------------

### Force MSVC Compilers Temporarily

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/how-to-guides/meson-args.rst

Pass the '--vsenv' argument to Meson build using 'build' or 'pip' to temporarily force the use of MSVC compilers on Windows.

```console
$ python -m build --wheel -Csetup-args="--vsenv" .
```

```console
$ python -m pip wheel -Csetup-args="--vsenv" .
```

--------------------------------

### Run Linters and Test Suite

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/how-to-guides/contributing.rst

Executes the code linter (ruff), type checker (mypy), and the test suite (pytest).

```console
$ ruff check
$ mypy
$ pytest
```

--------------------------------

### Define Package Metadata in pyproject.toml

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/index.rst

Override and extend package metadata using the standard format in the [project] section of pyproject.toml. This includes name, version, description, readme, license, and authors.

```toml
[project]
name = 'example'
version = '1.0.0'
description = 'Example package using the meson-python build backend'
readme = 'README.rst'
license = {file = 'LICENSE.txt'}
authors = [
  {name = 'Au Thor', email = 'author@example.com'},
]

[project.scripts]
example = 'example.cli:main'

```

--------------------------------

### Exclude Files from Wheel

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/how-to-guides/shared-libraries.rst

Configure Meson-Python to exclude specific files or directories from the Python wheel. This is done using the `exclude` option in the `tool.meson-python.wheel` configuration.

```toml
[tool.meson-python.wheel]
exclude = ['{prefix}/include/*']
```

--------------------------------

### Generate Export Header

Source: https://github.com/mesonbuild/meson-python/blob/main/tests/packages/cmake-subproject/subprojects/cmaketest/CMakeLists.txt

Includes the 'GenerateExportHeader' module and uses it to generate an export header for the 'cmaketest' library. This is useful for managing symbols in shared libraries.

```cmake
include(GenerateExportHeader)
generate_export_header(cmaketest)
```

--------------------------------

### Unset Optimization Flags in Conda

Source: https://github.com/mesonbuild/meson-python/blob/main/docs/how-to-guides/debug-builds.rst

When using Conda, environment variables like CFLAGS and CXXFLAGS can override debug build settings. Unset them to ensure optimization flags do not interfere with the debug build.

```console
unset CFLAGS
unset CXXFLAGS
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.