diff --git a/docs/Config.md b/docs/Config.md index ed700ac..6cf799a 100644 --- a/docs/Config.md +++ b/docs/Config.md @@ -118,31 +118,60 @@ Additionally, two extra configuration files can be placed in the same directory - `py-build-cmake.local.toml`: the options in this file override the values in the `tool.py-build-cmake` section of `pyproject.toml`.
This is useful if you need specific arguments or CMake options to compile the package on your system. - `py-build-cmake.cross.toml`: the options in this file override the values in the `tool.py-build-cmake.cross` section of `pyproject.toml`.
Useful for cross-compiling the package without having to edit the main configuration file. -# Command line overrides +It is recommended to exclude these files from version control, e.g. by adding them to your `.gitignore`. -Instead of using the `py-build-cmake.local.toml` and `py-build-cmake.cross.toml` files, you can also include additional config files using command line options: + +# Command-line overrides + +Instead of using the `py-build-cmake.local.toml` and `py-build-cmake.cross.toml` files, you can also include additional config files using command-line options: - `--local`: specifies a toml file that overrides the `tool.py-build-cmake` section of `pyproject.toml`, similar to `py-build-cmake.local.toml` - `--cross`: specifies a toml file that overrides the `tool.py-build-cmake.cross` section of `pyproject.toml`, similar to `py-build-cmake.cross.toml` -These command line overrides are applied after the `py-build-cmake.local.toml` and `py-build-cmake.cross.toml` files in the project folder (if any). +These command-line overrides are applied after the `py-build-cmake.local.toml` and `py-build-cmake.cross.toml` files in the project folder (if any). When using PyPA build, these flags can be specified using the `-C` or `--config-setting` flag: ```sh python -m build . -C--cross=/path/to/my-cross-config.toml ``` -The same flag may appear multiple times, for example: +The same flag may appear multiple times. The order for the same flag is preserved, but all `--cross` flags are applied after all `--local` flags. For example: ```sh python -m build . -C--local=conf-A.toml -C--local=conf-B.toml ``` -For PyPA pip, you can use the `--config-settings` flag instead. +For PyPA pip, you can use the `-C` or `--config-settings` flags instead. + +Finally, you can also specify overrides for specific configuration options on the command-line, for example: +```sh +python -m build . \ + -C override=cmake.options.CMAKE_PREFIX_PATH+="/opt/some-package" \ + -C override=cmake.env.PATH=+(path)"/opt/some-package/bin" +``` +The format consists of the configuration option keys (separated) by periods, followed by an operator (such as `+=`, see below), followed by the value. + +The following operators are supported: +- `=`: Sets the configuration option regardless of its previous value. +- `+=`: Appends the given value to the previous value. +- `=+`: Prepends the given value to the previous value. +- `=-`: Removes the given value from the previous value. +- `=!`: Clears the configuration option if set. +- `+=(path)`: Appends the given value to the previous value, joining them with the system's path separator (`:` on Unix, `;` on Windows). +- `=+(path)`: Prepends the given value to the previous value, joining them with the system's path separator. + +Values can be specified using a TOML-like syntax, using square brackets for lists, and curly braces with equal signs for dictionaries. Simple strings can be specified without quotes, but quotes are required when including special characters. Note the escaping of quotes to prevent the shell from stripping them out. +```sh +python -m build . \ + -C "override=cmake.options.CMAKE_PREFIX_PATH=[\"/opt/some-package\", \"/another\"]" \ + -C "override=cmake.env={MY_PATH = \"/opt/some-package\" }" \ + -C "override=cmake.find_python=true" +``` + # Combining lists Many options are specified as lists of strings. When one of these options inherits from or is overridden by another option, these lists can be merged in different ways. In the table above, when the data type is `list`, the original list of options is simply replaced by the list it is overridden by. -When the data type is `list+`, the value of the overriding option is appended to the original value. This is used primarily for combining lists of command line options. +When the data type is `list+`, the value of the overriding option is appended to the original value. This is used primarily for combining lists of command-line options. If you want full control of what happens when overriding a list option, you can use a dictionary with one or more of the following keys: diff --git a/src/py_build_cmake/cli.py b/src/py_build_cmake/cli.py index be0888b..127a972 100644 --- a/src/py_build_cmake/cli.py +++ b/src/py_build_cmake/cli.py @@ -243,20 +243,22 @@ def format(md, component): "- `py-build-cmake.cross.toml`: the options in this file " "override the values in the `tool.py-build-cmake.cross` section " "of `pyproject.toml`.
Useful for cross-compiling the " - "package without having to edit the main configuration file.\n" + "package without having to edit the main configuration file.\n\n" + "It is recommended to exclude these files from version control, " + "e.g. by adding them to your `.gitignore`.\n\n" ) - pr_md("# Command line overrides\n") + pr_md("# Command-line overrides\n") pr_md( "Instead of using the `py-build-cmake.local.toml` and " "`py-build-cmake.cross.toml` files, you can also include " - "additional config files using command line options:\n\n" + "additional config files using command-line options:\n\n" "- `--local`: specifies a toml file that overrides the " "`tool.py-build-cmake` section of `pyproject.toml`, " "similar to `py-build-cmake.local.toml`\n" "- `--cross`: specifies a toml file that overrides the " "`tool.py-build-cmake.cross` section of `pyproject.toml`, " "similar to `py-build-cmake.cross.toml`\n\n" - "These command line overrides are applied after the " + "These command-line overrides are applied after the " "`py-build-cmake.local.toml` and `py-build-cmake.cross.toml` " "files in the project folder (if any).\n\n" "When using PyPA build, these flags can be specified using " @@ -264,12 +266,49 @@ def format(md, component): "```sh\n" "python -m build . -C--cross=/path/to/my-cross-config.toml\n" "```\n" - "The same flag may appear multiple times, for example: \n" + "The same flag may appear multiple times. The order for the same " + "flag is preserved, but all `--cross` flags are applied after all " + "`--local` flags. For example: \n" "```sh\n" "python -m build . -C--local=conf-A.toml -C--local=conf-B.toml\n" "```\n" - "For PyPA pip, you can use the `--config-settings` flag " - "instead.\n" + "For PyPA pip, you can use the `-C` or `--config-settings` flags " + "instead.\n\n" + "Finally, you can also specify overrides for specific " + "configuration options on the command-line, for example:\n" + "```sh\n" + "python -m build . \\\n" + ' -C override=cmake.options.CMAKE_PREFIX_PATH+="/opt/some-package" \\\n' + ' -C override=cmake.env.PATH=+(path)"/opt/some-package/bin"\n' + "```\n" + "The format consists of the configuration option keys (separated) " + "by periods, followed by an operator (such as `+=`, see below), " + "followed by the value.\n\n" + "The following operators are supported:\n" + "- `=`: Sets the configuration option regardless of its previous " + "value.\n" + "- `+=`: Appends the given value to the previous value.\n" + "- `=+`: Prepends the given value to the previous value.\n" + "- `=-`: Removes the given value from the previous value.\n" + "- `=!`: Clears the configuration option if set.\n" + "- `+=(path)`: Appends the given value to the previous value, " + "joining them with the system's path separator (`:` on Unix, `;` " + "on Windows).\n" + "- `=+(path)`: Prepends the given value to the previous value, " + "joining them with the system's path separator.\n\n" + "Values can be specified using a TOML-like syntax, using square " + "brackets for lists, and curly braces with equal signs for " + "dictionaries. Simple strings can be specified without quotes, " + "but quotes are required when including special characters. " + "Note the escaping of quotes to prevent the shell from stripping " + "them out.\n" + "```sh\n" + "python -m build . \\\n" + ' -C "override=cmake.options.CMAKE_PREFIX_PATH=' + '[\\"/opt/some-package\\", \\"/another\\"]" \\\n' + ' -C "override=cmake.env={MY_PATH = \\"/opt/some-package\\" }" \\\n' + ' -C "override=cmake.find_python=true"\n' + "```\n\n" ) pr_md("# Combining lists\n") pr_md( @@ -281,7 +320,7 @@ def format(md, component): "by. \n" "When the data type is `list+`, the value of the overriding " "option is appended to the original value. This is used primarily " - "for combining lists of command line options.\n\n" + "for combining lists of command-line options.\n\n" "If you want full control of what happens when overriding a list " "option, you can use a dictionary with one or more of the " "following keys:\n\n"