feat: support --pgo for maturin develop (#3270)

Author: messense

guide/src/local_development.md

@@ -20,6 +20,13 @@ Options:
 
           [possible values: pyo3, pyo3-ffi, cffi, uniffi, bin]
 
+      --pgo
+          Build with Profile-Guided Optimization (PGO).
+
+          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.
+
+          Implies `--release` unless `--profile` is specified.
+
       --strip
           Strip the library for minimum file size
 

src/develop/mod.rs

@@ -39,6 +39,15 @@ pub struct DevelopOptions {
     /// Pass --release to cargo
     #[arg(short = 'r', long, help_heading = heading::COMPILATION_OPTIONS, conflicts_with = "profile")]
     pub release: bool,
+    /// Build with Profile-Guided Optimization (PGO).
+    ///
+    /// 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.
+    ///
+    /// Implies `--release` unless `--profile` is specified.
+    #[arg(long)]
+    pub pgo: bool,
     /// Strip the library for minimum file size
     #[arg(long)]
     pub strip: bool,
@@ -324,6 +333,7 @@ pub fn develop(develop_options: DevelopOptions, venv_dir: &Path) -> Result<()> {
     let DevelopOptions {
         bindings,
         release,
+        pgo,
         strip,
         extras,
         group,
@@ -340,6 +350,11 @@ pub fn develop(develop_options: DevelopOptions, venv_dir: &Path) -> Result<()> {
     if release {
         cargo_options.profile = Some("release".to_string());
     }
+    // PGO-optimizing a debug build makes no sense, so `--pgo` implies the
+    // release profile unless another profile was requested explicitly
+    if pgo && cargo_options.profile.is_none() {
+        cargo_options.profile = Some("release".to_string());
+    }
 
     let mut target_triple = cargo_options.target.clone();
     let target = Target::from_target_triple(cargo_options.target.as_ref())?;
@@ -385,6 +400,7 @@ pub fn develop(develop_options: DevelopOptions, venv_dir: &Path) -> Result<()> {
         .into_build_context()
         .strip(if strip { Some(true) } else { None })
         .editable(true)
+        .pgo(pgo)
         .build()?;
 
     // Ensure that version information is present, https://github.com/PyO3/maturin/issues/2416

tests/cmd/develop.stdout

@@ -12,6 +12,14 @@ Options:
 
           [possible values: pyo3, pyo3-ffi, cffi, uniffi, bin]
 
+      --pgo
+          Build with Profile-Guided Optimization (PGO).
+          
+          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.
+          
+          Implies `--release` unless `--profile` is specified.
+
       --strip
           Strip the library for minimum file size
 

tests/common/develop.rs

@@ -105,6 +105,7 @@ pub fn test_develop(case: &DevelopCase<'_>) -> Result<()> {
     let develop_options = DevelopOptions {
         bindings: case.bindings.map(|binding| binding.to_owned()),
         release: false,
+        pgo: false,
         strip: false,
         extras: Vec::new(),
         group: Vec::new(),