Refactor schema.rs using a cargo command builder (pgcentralfoundation#2187)

I find the code in schema.rs to be poorly factored in general.
A great deal of code is repeated in `first_build` and `second_build`.
In other places, arguments are created long before they are needed.
All of this makes it hard to follow basic data flow or
understand what is distinct about each invocation.

First, split some functions more finely to make it easier to follow
where arguments are used.
- `compute_symbols` grows `find_and_compute_symbols` as its "front end"
- `generate_schema` forks into `_for_cli` and `_implicit`

Secondly, absorb repeated code in `first_build` and `second_build`
into `cargo_pgrx::cargo::Cargo`, a builder for `process::Command`s.

This doesn't _entirely_ "pay off" yet due to the weight of boilerplate,
some of the distinctions being still weak, and not all sites in
cargo-pgrx using improved abstractions. This will improve over time.

Author: workingjubilee

cargo-pgrx/src/cargo.rs

@@ -7,6 +7,178 @@
 //LICENSE All rights reserved.
 //LICENSE
 //LICENSE Use of this source code is governed by the MIT license that can be found in the LICENSE file.
+use crate::profile::CargoProfile;
+use std::collections::BTreeMap;
+use std::path::PathBuf;
+use std::{env, process};
+
+/// Configuration for building a cargo execution
+#[derive(Default, Clone, Debug)]
+pub struct Cargo {
+    subcmd: String,
+    features: clap_cargo::Features,
+    stdio: [Stdio; 3],
+    manifest: Option<PathBuf>,
+    package: String,
+    log_level: Option<String>,
+    target: Option<String>,
+    profile: CargoProfile,
+    // use a BTreeMap for deterministic order of iteration
+    more_args: BTreeMap<String, Vec<String>>,
+}
+
+impl Cargo {
+    pub fn subcommand(mut self, s: &str) -> Self {
+        self.subcmd.clear();
+        self.subcmd.push_str(s);
+        self
+    }
+
+    pub fn std_streams(mut self, streams: [Stdio; 3]) -> Self {
+        self.stdio = streams;
+        self
+    }
+
+    pub fn manifest_path(mut self, path: Option<PathBuf>) -> Self {
+        self.manifest = path;
+        self
+    }
+
+    pub fn package(mut self, package: String) -> Self {
+        self.package = package;
+        self
+    }
+
+    pub fn target(mut self, target: Option<String>) -> Self {
+        self.target = target;
+        self
+    }
+
+    pub fn profile(mut self, profile: CargoProfile) -> Self {
+        self.profile = profile;
+        self
+    }
+
+    pub fn log_level(mut self, level: Option<String>) -> Self {
+        self.log_level = level;
+        self
+    }
+
+    pub fn flag(mut self, flag: impl Into<String>) -> Self {
+        self.more_args.insert(flag.into(), Vec::new());
+        self
+    }
+
+    pub fn flag_args(mut self, flag: impl Into<String>, args: Vec<String>) -> Self {
+        self.more_args.insert(flag.into(), args);
+        self
+    }
+
+    pub fn features(mut self, features: clap_cargo::Features) -> Self {
+        self.features = features;
+        self
+    }
+
+    #[track_caller]
+    pub fn into_command(self) -> process::Command {
+        let mut cmd = cargo();
+
+        // subcommand *must* go first
+        if self.subcmd != "" {
+            cmd.arg(&self.subcmd);
+        } else {
+            panic!("`Cargo::into_command` requires a subcommand to be set, was: {self:?}")
+        }
+
+        let Cargo {
+            features,
+            stdio,
+            manifest,
+            log_level,
+            target,
+            profile,
+            package,
+            subcmd: _,
+            more_args,
+        } = self;
+
+        // set most-interesting flags first, like profile, target, and manifest-path
+        // so that when we read dumped command lines we can see that info first
+        cmd.args(profile.cargo_args());
+
+        if let Some(target) = target {
+            cmd.arg("--target").arg(target);
+        }
+        if let Some(manifest) = manifest {
+            cmd.arg("--manifest-path").arg(manifest);
+        }
+        if !package.is_empty() {
+            cmd.arg("--package").arg(package);
+        }
+
+        // set std streams
+        let [stdin, stdout, stderr] = stdio;
+        if let Some(stdio) = stdin.into_stdio() {
+            cmd.stdin(stdio);
+        }
+        if let Some(stdio) = stdout.into_stdio() {
+            cmd.stdout(stdio);
+        }
+        if let Some(stdio) = stderr.into_stdio() {
+            cmd.stderr(stdio);
+        }
+
+        // set features
+        if features.no_default_features {
+            cmd.arg("--no-default-features");
+        }
+
+        if features.all_features {
+            cmd.arg("--all-features");
+        }
+
+        if !features.features.is_empty() {
+            cmd.arg("--features");
+            cmd.arg(features.features.join(" "));
+        }
+
+        // And now the miscellaneous build flags!
+        let flags = env::var("PGRX_BUILD_FLAGS").unwrap_or_default();
+        for arg in flags.split_ascii_whitespace() {
+            cmd.arg(arg);
+        }
+
+        // set envs
+        if let Some(log_level) = log_level {
+            cmd.env("RUST_LOG", log_level);
+        }
+
+        for (flag, args) in more_args {
+            cmd.arg(flag).args(args);
+        }
+
+        cmd
+    }
+}
+
+#[derive(Clone, Copy, Debug, Default, PartialEq)]
+pub enum Stdio {
+    Inherit,
+    Null,
+    #[default]
+    Default,
+}
+
+impl Stdio {
+    fn into_stdio(self) -> Option<process::Stdio> {
+        match self {
+            Stdio::Inherit => Some(process::Stdio::inherit()),
+            Stdio::Null => Some(process::Stdio::null()),
+            Stdio::Default => None,
+        }
+    }
+}
+
 pub(crate) fn cargo() -> std::process::Command {
     let cargo = std::env::var_os("CARGO").unwrap_or_else(|| "cargo".into());
     std::process::Command::new(cargo)