From 418d4453e7bad05131e39d269fcb3bf1affdd5db Mon Sep 17 00:00:00 2001 From: messense Date: Sun, 19 Jul 2026 19:53:17 +0800 Subject: [PATCH] feat: support MATURIN_PGO env var to activate --pgo Allow enabling Profile-Guided Optimization via the MATURIN_PGO environment variable in `maturin build`, `maturin publish`, `maturin develop` and PEP 517 builds (e.g. `pip install .`). Values are parsed leniently: `0`, `false`, `no`, `off` or an empty string disable it, anything else enables it. The pep517 subcommands also accept an explicit `--pgo` flag, so it can be passed through MATURIN_PEP517_ARGS as well. --- guide/src/distribution.md | 4 ++++ guide/src/environment-variables.md | 1 + guide/src/local_development.md | 4 ++++ src/commands/pep517.rs | 10 ++++++++++ src/develop/mod.rs | 4 +++- src/main.rs | 8 ++++++-- tests/cmd/build.stdout | 4 ++++ tests/cmd/develop.stdout | 4 ++++ tests/cmd/publish.stdout | 4 ++++ 9 files changed, 40 insertions(+), 3 deletions(-) diff --git a/guide/src/distribution.md b/guide/src/distribution.md index 6f63d0321..d8fddb198 100644 --- a/guide/src/distribution.md +++ b/guide/src/distribution.md @@ -55,6 +55,10 @@ Options: Requires `pgo-command` to be set in `[tool.maturin]` in pyproject.toml. This performs a three-phase build: instrumented build, profile training, and optimized rebuild. + Can also be enabled via the MATURIN_PGO environment variable. + + [env: MATURIN_PGO=] + -i, --interpreter [...] The python versions to build wheels for, given as the executables of interpreters such as `python3.9` or `/usr/bin/python3.8` diff --git a/guide/src/environment-variables.md b/guide/src/environment-variables.md index 2378a6b0c..5223748db 100644 --- a/guide/src/environment-variables.md +++ b/guide/src/environment-variables.md @@ -73,6 +73,7 @@ Config-settings take priority over `MATURIN_PEP517_ARGS`; the environment variab `MATURIN_PYODIDE_ABI_VERSION` when possible — wheels built with the legacy tag are not installable on PEP 783-compliant runtimes. * `MATURIN_STRIP`: Strip the library for minimum file size +* `MATURIN_PGO`: Build with Profile-Guided Optimization (same as `--pgo`), works with `maturin build`, `maturin develop` and PEP 517 builds (e.g. `pip install .`). Set to `0`, `false`, `no` or `off` to disable, any other value enables it * `MATURIN_NO_MISSING_BUILD_BACKEND_WARNING`: Suppress missing build backend warning * `MATURIN_USE_XWIN`: Set to `1` to force to use `xwin` for cross compiling even on Windows that supports native compilation * `ANDROID_API_LEVEL`: The Android API level to target when cross compiling for Android diff --git a/guide/src/local_development.md b/guide/src/local_development.md index 8d7c0f338..6fc776236 100644 --- a/guide/src/local_development.md +++ b/guide/src/local_development.md @@ -27,6 +27,10 @@ Options: Implies `--release` unless `--profile` is specified. + Can also be enabled via the MATURIN_PGO environment variable. + + [env: MATURIN_PGO=] + --strip Strip the library for minimum file size diff --git a/src/commands/pep517.rs b/src/commands/pep517.rs index 48651ab37..1522f55ff 100644 --- a/src/commands/pep517.rs +++ b/src/commands/pep517.rs @@ -26,6 +26,9 @@ pub enum Pep517Command { metadata_directory: PathBuf, #[command(flatten)] strip_opt: StripOption, + /// Build with Profile-Guided Optimization (PGO) + #[arg(long, env = "MATURIN_PGO", value_parser = clap::builder::FalseyValueParser::new())] + pgo: bool, }, #[command(name = "build-wheel")] /// Implementation of build_wheel @@ -34,6 +37,9 @@ pub enum Pep517Command { build_options: BuildOptions, #[command(flatten)] strip_opt: StripOption, + /// Build with Profile-Guided Optimization (PGO) + #[arg(long, env = "MATURIN_PGO", value_parser = clap::builder::FalseyValueParser::new())] + pgo: bool, /// Build editable wheels #[arg(long)] editable: bool, @@ -86,12 +92,14 @@ pub fn pep517(subcommand: Pep517Command) -> Result<()> { mut build_options, metadata_directory, strip_opt, + pgo, } => { require_single_interpreter(&mut build_options, "write-dist-info")?; let mut context = build_options .into_build_context() .strip(strip_opt.strip) .editable(false) + .pgo(pgo) .build()?; ensure_release_profile(&mut context); @@ -111,6 +119,7 @@ pub fn pep517(subcommand: Pep517Command) -> Result<()> { Pep517Command::BuildWheel { mut build_options, strip_opt, + pgo, editable, } => { require_single_interpreter(&mut build_options, "build-wheel")?; @@ -118,6 +127,7 @@ pub fn pep517(subcommand: Pep517Command) -> Result<()> { .into_build_context() .strip(strip_opt.strip) .editable(editable) + .pgo(pgo) .build()?; ensure_release_profile(&mut build_context); diff --git a/src/develop/mod.rs b/src/develop/mod.rs index 40b2b3039..191a601ef 100644 --- a/src/develop/mod.rs +++ b/src/develop/mod.rs @@ -46,7 +46,9 @@ pub struct DevelopOptions { /// and optimized rebuild. /// /// Implies `--release` unless `--profile` is specified. - #[arg(long)] + /// + /// Can also be enabled via the MATURIN_PGO environment variable. + #[arg(long, env = "MATURIN_PGO", value_parser = clap::builder::FalseyValueParser::new())] pub pgo: bool, /// Strip the library for minimum file size #[arg(long)] diff --git a/src/main.rs b/src/main.rs index 9873f0402..df5107c0f 100644 --- a/src/main.rs +++ b/src/main.rs @@ -77,7 +77,9 @@ enum Command { /// Requires `pgo-command` to be set in `[tool.maturin]` in pyproject.toml. /// This performs a three-phase build: instrumented build, profile training, /// and optimized rebuild. - #[arg(long)] + /// + /// Can also be enabled via the MATURIN_PGO environment variable. + #[arg(long, env = "MATURIN_PGO", value_parser = clap::builder::FalseyValueParser::new())] pgo: bool, #[command(flatten)] build: BuildOptions, @@ -98,7 +100,9 @@ enum Command { /// Build with Profile-Guided Optimization (PGO). /// /// Requires `pgo-command` to be set in `[tool.maturin]` in pyproject.toml. - #[arg(long)] + /// + /// Can also be enabled via the MATURIN_PGO environment variable. + #[arg(long, env = "MATURIN_PGO", value_parser = clap::builder::FalseyValueParser::new())] pgo: bool, #[command(flatten)] publish: PublishOpt, diff --git a/tests/cmd/build.stdout b/tests/cmd/build.stdout index 1dd2a513c..0f4e8b7b2 100644 --- a/tests/cmd/build.stdout +++ b/tests/cmd/build.stdout @@ -25,6 +25,10 @@ Options: Requires `pgo-command` to be set in `[tool.maturin]` in pyproject.toml. This performs a three-phase build: instrumented build, profile training, and optimized rebuild. + + Can also be enabled via the MATURIN_PGO environment variable. + + [env: MATURIN_PGO=] -i, --interpreter [...] The python versions to build wheels for, given as the executables of interpreters such as diff --git a/tests/cmd/develop.stdout b/tests/cmd/develop.stdout index a90f96982..a1918685a 100644 --- a/tests/cmd/develop.stdout +++ b/tests/cmd/develop.stdout @@ -19,6 +19,10 @@ Options: three-phase build: instrumented build, profile training, and optimized rebuild. Implies `--release` unless `--profile` is specified. + + Can also be enabled via the MATURIN_PGO environment variable. + + [env: MATURIN_PGO=] --strip Strip the library for minimum file size diff --git a/tests/cmd/publish.stdout b/tests/cmd/publish.stdout index 6351a1805..e49365de0 100644 --- a/tests/cmd/publish.stdout +++ b/tests/cmd/publish.stdout @@ -20,6 +20,10 @@ Options: Build with Profile-Guided Optimization (PGO). Requires `pgo-command` to be set in `[tool.maturin]` in pyproject.toml. + + Can also be enabled via the MATURIN_PGO environment variable. + + [env: MATURIN_PGO=] -r, --repository The repository (package index) to upload the package to. Should be a section in the config