Generate Ninja build file on the fly

Cargo.toml

@@ -16,6 +16,7 @@ itertools = "0.12"
 tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["fmt"] }
 serde_json = "1"
+tempfile = "3.8.0"
 
 [lints.clippy]
 pedantic = { level = "warn", priority = -1 }
@@ -62,7 +63,6 @@ rstest = "0.18.0"
 cucumber = "0.20.0"
 tokio = { version = "1", features = ["macros", "rt-multi-thread"], default-features = false }
 insta = { version = "1", features = ["yaml"] }
-tempfile = "3"
 serial_test = "3"
 
 [[test]]

docs/netsuke-design.md

@@ -1348,13 +1348,8 @@ entire CLI specification.
 Rust
 
 ```rust
-// In src/main.rs
+use clap::{Parser, Subcommand};
 
-#[rustfmt::skip]
-use clap::Parser;
-#[rustfmt::skip]
-use clap::Subcommand;
-#[rustfmt::skip]
 use std::path::PathBuf;
 
 #[derive(Parser)]
@@ -1380,11 +1375,22 @@ struct Cli { /// Path to the Netsuke manifest file to use.
 
 #[derive(Subcommand)]
 enum Commands { /// Build specified targets (or default targets if none are
-given) [default]. Build { /// A list of specific targets to build. targets:
-Vec<String>, },
+given) [default]. Build { /// Write the generated Ninja manifest to this path
+and retain it.
+        #[arg(long, value_name = "FILE")]
+        emit: Option<PathBuf>,
 
-    /// Remove build artefacts and intermediate files. Clean {}, /// Display
-    the build dependency graph in DOT format for visualisation. Graph {}, }
+        /// A list of specific targets to build. targets: Vec<String>, },
+
+    /// Remove build artefacts and intermediate files. Clean {},
+
+    /// Display the build dependency graph in DOT format for visualisation.
+    Graph {},
+
+    /// Emit the Ninja manifest to `FILE` without invoking Ninja. Emit { ///
+    Output path for the generated Ninja file.
+        #[arg(value_name = "FILE")]
+        file: PathBuf, }, }
 ```
 
 *Note: The* `Build` *command is wrapped in an* `Option<Commands>` *and will be
@@ -1395,12 +1401,14 @@ treated as the default subcommand if none is provided, allowing for the common*
 
 The behaviour of each subcommand is clearly defined:
 
-- `Netsuke build [targets...]`: This is the primary and default command. It
-  executes the full five-stage pipeline: ingestion, Jinja rendering, YAML
-  parsing, IR generation, and Ninja synthesis. It then invokes `ninja` to build
-  the list of specified `targets`. If no targets are provided on the command
-  line, it will build the targets listed in the `defaults` section of the
-  manifest.
+- `Netsuke build [--emit FILE] [targets...]`: This is the primary and default
+  command. It executes the full five-stage pipeline: ingestion, Jinja
+  rendering, YAML parsing, IR generation, and Ninja synthesis. By default the
+  generated Ninja file is written to a securely created temporary location and
+  removed after the build completes. Supplying `--emit FILE` writes the Ninja
+  file to `FILE` and retains it. If no targets are provided on the command
+  line, the targets listed in the `defaults` section of the manifest are
+  built.
 
 - `Netsuke clean`: This command provides a convenient way to clean the build
   directory. It will invoke the Ninja backend with the appropriate flags, such
@@ -1414,6 +1422,10 @@ The behaviour of each subcommand is clearly defined:
   Dagre.js viewer. Visualizing the graph is invaluable for understanding and
   debugging complex projects.
 
+- `Netsuke emit FILE`: This command performs the pipeline up to Ninja
+  synthesis and writes the resulting Ninja file to `FILE` without invoking
+  Ninja.
+
 ### 8.4 Design Decisions
 
 The CLI is implemented using clap's derive API in `src/cli.rs`. Clap's

src/cli.rs

@@ -72,6 +72,7 @@ impl Cli {
     fn with_default_command(mut self) -> Self {
         if self.command.is_none() {
             self.command = Some(Commands::Build {
+                emit: None,
                 targets: Vec::new(),
             });
         }
@@ -84,6 +85,10 @@ impl Cli {
 pub enum Commands {
     /// Build specified targets (or default targets if none are given) [default].
     Build {
+        /// Write the generated Ninja manifest to this path and retain it.
+        #[arg(long, value_name = "FILE")]
+        emit: Option<PathBuf>,
+
         /// A list of specific targets to build.
         targets: Vec<String>,
     },
@@ -93,4 +98,11 @@ pub enum Commands {
 
     /// Display the build dependency graph in DOT format for visualization.
     Graph,
+
+    /// Emit the Ninja manifest to the specified file without running Ninja.
+    Emit {
+        /// Output path for the generated Ninja file.
+        #[arg(value_name = "FILE")]
+        file: PathBuf,
+    },
 }