ENH: rename the buildir config setting to build-dir

The old name is still accepted for backward compatibility.

Fixes #275.

Author: dnicolodi

docs/how-to-guides/build-directory.rst

@@ -11,9 +11,9 @@ Use a permanent build directory
 
 .. todo::
 
-   - Explain why you'd want to use the ``builddir`` option
+   - Explain why you'd want to use the ``build-dir`` option
      - Mention it works properly when using ``--cross-file`` (eg. https://github.com/scipy/scipy/blob/1c836efe5ff37ffa4490756269b060a464690e62/.github/workflows/wheels.yml#L180-L188)
-   - Explain how ``builddir`` works
+   - Explain how ``build-dir`` works
    - Warn that user-configured build directories are "use at your own risk"
    - Warn that ``meson-python`` version mismatches in the build directory can
      cause trouble

docs/how-to-guides/debug-builds.rst

@@ -23,7 +23,7 @@ We can do all that with the following ``pip`` invocation:
 
     $ pip install -e . --no-build-isolation \
         -Csetup-args=-Dbuildtype=debug \
-        -Cbuilddir=build-dbg
+        -Cbuild-dir=build-dbg
 
 This debug build of your package will work with either a regular or debug build
 of your Python interpreter. A debug Python interpreter isn't necessary, but may

docs/how-to-guides/editable-installs.rst

@@ -105,7 +105,7 @@ to install the same project in editable mode for multiple interpreters
 with different ABIs.
 
 An alternative build directory can be specified using the
-:option:`builddir` config setting.
+:option:`build-dir` config setting.
 
 
 .. _how-to-guides-editable-installs-verbose:

docs/reference/config-settings.rst

@@ -14,9 +14,9 @@ settings you can pass when building the project. Please refer to the
 :ref:`how-to-guides-meson-args` guides for information on how to use
 them.
 
-.. option:: builddir
+.. option:: build-dir
 
-   By default ``meson-python`` uses a temporary builds directory.
+   By default ``meson-python`` uses a temporary build directory.
    This settings allows to select the Meson build directory and
    prevents it to be deleted when ``meson-python`` terminates.  If the
    directory does not exists, it will be created.  If the directory
@@ -27,6 +27,9 @@ them.
    ``meson-python``. This avoids having to rebuild the whole project
    when testing changes during development.
 
+   For backward comaptibility reasons, the alternative ``builddir``
+   spelling is also accepted.
+
 .. option:: dist-args
 
    Extra arguments to be passed to the ``meson dist`` command.

mesonpy/__init__.py

@@ -583,6 +583,7 @@ def _string_or_strings(value: Any, name: str) -> List[str]:
 
     options = {
         'builddir': _string,
+        'build-dir': _string,
         'editable-verbose': _bool,
         'dist-args': _string_or_strings,
         'setup-args': _string_or_strings,
@@ -602,6 +603,17 @@ def _string_or_strings(value: Any, name: str) -> List[str]:
             else:
                 raise ConfigError(f'Unknown option "{key}"')
         config[key] = parser(value, key)
+
+    # Check backward compatibility aliases.
+    aliases = {
+        'build-dir': 'builddir',
+    }
+    for key, alt in aliases.items():
+        if key in config and alt in config:
+            raise ConfigError(f'Option "{alt}" is a backward compatibility alias for "{key}". Only one can be used')
+        if alt in config:
+            config[key] = config[alt]
+
     return config
 
 
@@ -942,7 +954,7 @@ def _project(config_settings: Optional[Dict[Any, Any]] = None) -> Iterator[Proje
     settings = _validate_config_settings(config_settings or {})
     meson_args = typing.cast(MesonArgs, {name: settings.get(f'{name}-args', []) for name in _MESON_ARGS_KEYS})
     source_dir = os.path.curdir
-    build_dir = settings.get('builddir')
+    build_dir = settings.get('build-dir')
     editable_verbose = bool(settings.get('editable-verbose'))
 
     with contextlib.ExitStack() as ctx:
@@ -1081,15 +1093,15 @@ def build_editable(
 ) -> str:
     _setup_cli()
 
-    # force set a permanent builddir
+    # Force set a permanent build directory.
     if not config_settings:
         config_settings = {}
-    if 'builddir' not in config_settings:
-        builddir = pathlib.Path('build')
-        builddir.mkdir(exist_ok=True)
-        if not next(builddir.iterdir(), None):
-            _add_ignore_files(builddir)
-        config_settings['builddir'] = os.fspath(builddir / str(mesonpy._tags.get_abi_tag()))
+    if 'build-dir' not in config_settings and 'builddir' not in config_settings:
+        build_dir = pathlib.Path('build')
+        build_dir.mkdir(exist_ok=True)
+        if not next(build_dir.iterdir(), None):
+            _add_ignore_files(build_dir)
+        config_settings['build-dir'] = os.fspath(build_dir / str(mesonpy._tags.get_abi_tag()))
 
     out = pathlib.Path(wheel_directory)
     with _project(config_settings) as project: