diff --git a/README.md b/README.md index 1f210ce613..5028d790f5 100644 --- a/README.md +++ b/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..editor. -``` - -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 diff --git a/doc/nix.md b/doc/nix.md new file mode 100644 index 0000000000..558257615b --- /dev/null +++ b/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..[.dev][.double].[.nothreads][.] +``` + +## 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). diff --git a/flake.nix b/flake.nix index 79456bcba3..45292a8126 100644 --- a/flake.nix +++ b/flake.nix @@ -46,6 +46,8 @@ ]; commonDeps = with pkgs; [ + stdenv.cc + gcc-unwrapped pkg-config installShellFiles python3 @@ -64,7 +66,6 @@ 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 ({ @@ -72,17 +73,121 @@ 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 <&2 + exit 1 + fi + + exec "$binary_path" "''${runtime_args[@]}" ''; in { default = {