BUG: build.rs static Cargo.toml file declarations

[qknight]

build.rs static Cargo.toml file declarations

Some build.rs files simply generate code like a generated.rs and as input they use files from the project_root. For nix it would be important to know the input files for this generator step before the build_script_run is executed so we can create a minimal file list as the input and thus use the nix file monitoring to know when to rebuild - otherwise if we put all files in we will rebuild too often.

Here is a proposal:

[package]
name = "my-crate"
version = "0.1.0"

[build-script]
files = [
    "src/extra/*.c",
    "include/**/*.h",
    "data/config.json",
]
envs = ["MY_BUILD_VAR"]

types

Grok made this nice graph for types:

Is the file logically part of THIS crate?
├── Yes ──> Put it inside the crate root (protos/, migrations/, shaders/, etc)
│             └─> Very common & accepted pattern in 2025
└─ No ──> Is it shared between multiple crates?
          ├── Yes ──> Use workspace + path dependency or separate crate
          │           └─> preferred long-term solution
          └── No  ──> Is it third-party / generated / optional?
                      ├── Yes ──> Consider git submodule / vendoring / download in build.rs
                      │           └─> tolerated, but document heavily + add good CI checks
                      └── No  ──> You probably have an architectural problem

permissions:

We could have extend the Cargo.toml's [build-script] section with these permissions:

• CRATE_FILE_READ
• HOST_FS_READ
• HOST_FS_WRITE
• INTERNET_ACCESS

If they are not set, certain capabilities can't be used.

This way we could see if we can or want to execute a build_script_build at all.

On Nix we can use:

• CRATE_FILE_READ
  This would be implied by setting files = [ ... ] but if no such record is there we could map the whole project_source folder into and then use https://nixos.wiki/wiki/Ca-derivations to only rebuild dependencies when needed.
• HOST_FS_READ
  https://nix.dev/manual/nix/2.23/command-ref/conf-file.html?highlight=sandbox#conf-sandbox
• HOST_FS_WRITE
  https://nix.dev/manual/nix/2.23/command-ref/conf-file.html?highlight=sandbox#conf-sandbox
• INTERNET_ACCESS
  https://nix.dev/manual/nix/2.21/contributing/experimental-features#xp-feature-impure-derivations for INTERNET_ACCESS.