Improve Nix flake app build flag support

README.md

@@ -63,21 +63,7 @@ nix run .
 
 This will automatically install all build dependencies and compile Redot if the binary doesn't exist.
 
-For manual control over the build process:
-
-```bash
-# Enter the Nix development environment
-nix develop
-
-# Build Redot (use 'macos' on macOS, 'linuxbsd' on Linux)
-scons platform=linuxbsd  # or: scons platform=macos
-
-# Run the editor - binary name reflects your platform and architecture
-# Examples: redot.linuxbsd.editor.x86_64, redot.macos.editor.arm64
-./bin/redot.<platform>.editor.<arch>
-```
-
-Nix works on Linux and macOS, and is available at [nixos.org/download.html](https://nixos.org/download.html). The `nix run .` command automatically detects your platform and architecture.
+Detailed Nix usage, including passing SCons build flags through `nix run`, forwarding runtime arguments, and manual `nix develop` workflows, is documented in the `Nix usage guide` at `doc/nix.md`.
 
 
 ## Community and contributing

doc/nix.md

@@ -0,0 +1,70 @@
+# Nix workflow
+
+If you have the Nix package manager installed, you can build and run the editor in one command:
+
+```bash
+nix run .
+```
+
+This automatically installs the required build dependencies and compiles Redot if a matching binary does not already exist.
+
+## Passing SCons build flags
+
+You can pass SCons build flags directly through `nix run`:
+
+```bash
+# Build with custom SCons flags, then run the editor.
+nix run . -- target=editor dev_build=yes num_jobs=12
+
+# Build a release template.
+nix run . -- target=template_release production=yes
+
+# Pass SCons build flags first, then `--`, then runtime args for the editor.
+nix run . -- target=editor dev_build=yes -- --path /tmp/project
+```
+
+Argument handling works like this:
+
+- The first `--` is consumed by Nix.
+- Arguments before the next `--` are passed to `scons`.
+- Arguments after the next `--` are passed to the built Redot binary.
+
+For a quick reminder of the wrapper syntax, run:
+
+```bash
+nix run . -- --help
+```
+
+This supports the same SCons flags documented by the build system, such as `production=yes`, `target=template_release`, `module_mono_enabled=yes`, `precision=double`, `ccflags=...`, and more.
+
+The wrapper only uses a subset of those flags when deciding which existing binary can be reused: `target`, `arch`, `dev_build`, `precision`, `threads`, and `extra_suffix`. Other SCons flags such as `production=yes`, `module_mono_enabled=yes`, or custom `ccflags` are still forwarded to `scons`, but they do not change the wrapper's reuse check.
+
+## Manual builds with `nix develop`
+
+For full manual control over the build process:
+
+```bash
+# Enter the Nix development environment.
+nix develop
+
+# Build Redot (use 'macos' on macOS, 'linuxbsd' on Linux).
+scons platform=linuxbsd  # or: scons platform=macos
+
+# Example with extra build flags.
+scons platform=linuxbsd target=template_release production=yes
+
+# Run the editor - binary names can include optional suffixes.
+# Examples:
+#   redot.linuxbsd.editor.x86_64
+#   redot.linuxbsd.editor.dev.x86_64
+#   redot.linuxbsd.editor.double.x86_64
+#   redot.linuxbsd.editor.x86_64.nothreads
+./bin/redot.<platform>.<target>[.dev][.double].<arch>[.nothreads][.<extra_suffix>]
+```
+
+## Notes
+
+- `nix run .` only auto-builds when the expected binary for the wrapper-managed naming fields does not exist yet.
+- If you want to rebuild with different flags after a binary was already produced, remove the existing binary first or use `nix develop` and run `scons` manually.
+- The flake app automatically detects your platform and architecture, and `arch=auto` resolves to the host architecture.
+- Nix works on Linux and macOS, and is available at [nixos.org/download.html](https://nixos.org/download.html).

flake.nix

@@ -46,6 +46,8 @@
           ];
 
           commonDeps = with pkgs; [
+            stdenv.cc
+            gcc-unwrapped
             pkg-config
             installShellFiles
             python3
@@ -64,25 +66,128 @@
           deps = if isDarwin then darwinDeps ++ commonDeps else linuxDeps ++ commonDeps;
           libraryPathVar = if isDarwin then "DYLD_LIBRARY_PATH" else "LD_LIBRARY_PATH";
           platform = if isDarwin then "macos" else "linuxbsd";
-          binary = if isDarwin then "redot.macos.editor.${arch}" else "redot.linuxbsd.editor.${arch}";
         });
   in {
     apps = forEachSupportedSystem ({
       pkgs,
       deps,
       libraryPathVar,
       platform,
-      binary,
       arch,
       ...
     }: let
       script = pkgs.writeShellScript "redot" ''
+        export PATH=${pkgs.lib.makeBinPath deps}:$PATH
         export ${libraryPathVar}=${pkgs.lib.makeLibraryPath deps}
-        if [ ! -f ./bin/${binary} ]; then
+
+        scons_args=()
+        runtime_args=()
+        parsing_runtime_args=0
+        show_help=0
+        target=editor
+        target_arch=${arch}
+        scons_platform=${platform}
+        dev_build=no
+        precision=single
+        threads=yes
+        extra_suffix=
+
+        for arg in "$@"; do
+          if [ "$parsing_runtime_args" -eq 0 ] && [ "$arg" = "--help" ]; then
+            show_help=1
+            continue
+          fi
+
+          if [ "$parsing_runtime_args" -eq 0 ] && [ "$arg" = "--" ]; then
+            parsing_runtime_args=1
+            continue
+          fi
+
+          if [ "$parsing_runtime_args" -eq 0 ]; then
+            case "$arg" in
+              target=*) target=''${arg#target=} ;;
+              arch=*)
+                target_arch=''${arg#arch=}
+                if [ "$target_arch" = "auto" ]; then
+                  target_arch=${arch}
+                fi
+                ;;
+              platform=*)
+                scons_platform=''${arg#platform=}
+                continue
+                ;;
+              dev_build=*) dev_build=''${arg#dev_build=} ;;
+              precision=*) precision=''${arg#precision=} ;;
+              threads=*) threads=''${arg#threads=} ;;
+              extra_suffix=*) extra_suffix=''${arg#extra_suffix=} ;;
+            esac
+
+            scons_args+=("$arg")
+          else
+            runtime_args+=("$arg")
+          fi
+        done
+
+        if [ "$show_help" -eq 1 ]; then
+          cat <<EOF
+Usage:
+  nix run .
+  nix run . -- [scons build flags...]
+  nix run . -- [scons build flags...] -- [redot runtime args...]
+
+Examples:
+  nix run .
+  nix run . -- target=editor dev_build=yes num_jobs=12
+  nix run . -- target=template_release production=yes
+  nix run . -- target=editor dev_build=yes -- --path /tmp/project
+
+Argument handling:
+  - The first '--' is consumed by Nix.
+  - Arguments before the next '--' are passed to SCons.
+  - Arguments after the next '--' are passed to the Redot binary.
+
+Notes:
+  - Common SCons flags include target=..., dev_build=yes, production=yes,
+    module_mono_enabled=yes, precision=double, num_jobs=..., and ccflags=...
+  - The wrapper auto-builds only when a matching binary is not already present.
+    Use 'nix develop' for full manual rebuild control.
+EOF
+          exit 0
+        fi
+
+        binary_pattern="redot.$scons_platform.''${target}"
+
+        if [ "$dev_build" = "yes" ]; then
+          binary_pattern="$binary_pattern.dev"
+        fi
+
+        if [ "$precision" = "double" ]; then
+          binary_pattern="$binary_pattern.double"
+        fi
+
+        binary_pattern="$binary_pattern.''${target_arch}"
+
+        if [ "$threads" = "no" ]; then
+          binary_pattern="$binary_pattern.nothreads"
+        fi
+
+        if [ -n "$extra_suffix" ]; then
+          binary_pattern="$binary_pattern.$extra_suffix"
+        fi
+
+        binary_path="./bin/$binary_pattern"
+
+        if [ ! -f "$binary_path" ]; then
           echo "Building Redot..."
-          scons platform=${platform}
+          scons "''${scons_args[@]}" platform=$scons_platform
         fi
-        exec ./bin/${binary} "$@"
+
+        if [ ! -f "$binary_path" ]; then
+          echo "Could not find a built Redot binary at $binary_path" >&2
+          exit 1
+        fi
+
+        exec "$binary_path" "''${runtime_args[@]}"
       '';
     in {
       default = {