Build scripts and build-time asset/platform glue

fn main()

Purpose: This is the entry point for the build script. It tells Cargo what changes should rerun the script, skips unsupported builds, and starts the Bubblewrap compilation when the target is Linux.

Data flow: It reads environment values such as the crate directory, target operating system, and skip flag. It prints instructions for Cargo, checks whether the build should continue, and either exits quietly or asks try_build_bwrap to compile Bubblewrap. If that compilation reports an error, it turns the error into a build failure.

Call relations: Cargo calls main automatically before compiling the crate. main does the broad decision-making, then hands the detailed Linux build work to try_build_bwrap. If try_build_bwrap cannot finish, main stops the whole build with a clear failure message.

Call graph: calls 1 internal fn (try_build_bwrap); 5 external calls (from, var, var_os, panic!, println!).

fn try_build_bwrap() -> Result<(), String>

Purpose: This function does the actual work of compiling Bubblewrap's C code and telling Cargo how to link it. It is used when the build target is Linux and Bubblewrap has not been explicitly skipped.

Data flow: It reads Cargo's manifest and output directories, finds the Bubblewrap source directory, asks pkg-config where libcap is installed, writes a small generated config.h file, and configures the C compiler with source files, include paths, and compile definitions. After compiling a library named standalone_bwrap, it prints Cargo link instructions and enables the bwrap_available build flag. It returns success if all of this works, or a readable error string if something is missing or cannot be written.

Call relations: main calls this after deciding that a Linux Bubblewrap build should happen. Inside, it calls resolve_bwrap_source_dir to find the C source tree before setting up the compiler. Its printed Cargo instructions are picked up by Cargo and affect how the Rust crate is compiled and linked.

Call graph: calls 1 internal fn (resolve_bwrap_source_dir); called by 1 (main); 7 external calls (from, new, new, var, format!, println!, write).

fn resolve_bwrap_source_dir(manifest_dir: &Path) -> Result<PathBuf, String>

Purpose: This function chooses where the Bubblewrap source code should come from. It lets developers override the source location with an environment variable, while falling back to the vendored copy in the repository.

Data flow: It receives the crate's manifest directory. It first checks CODEX_BWRAP_SOURCE_DIR; if that variable points to an existing directory, it returns that path, and if it points nowhere, it returns an error. If no override is set, it looks for ../vendor/bubblewrap relative to the crate. It returns that path if it exists, otherwise it returns an error explaining how to fix the missing source.

Call relations: try_build_bwrap calls this before compiling anything, because the compiler needs to know where the Bubblewrap C files are. This function acts like a source-code locator: it decides between a developer-provided checkout and the repository's bundled copy, then hands the chosen path back to the build step.

Call graph: called by 1 (try_build_bwrap); 4 external calls (join, from, var, format!).

fn main() -> Result<(), String>

Purpose: Runs as Cargo’s build script entry point and emits build instructions for embedding the Windows manifest into the setup helper executable. It does nothing for non-Windows targets.

Data flow: It reads environment variables that Cargo provides, such as the target operating system, target toolchain, and crate directory. From those values it decides whether a manifest is needed, builds the manifest file path, and prints Cargo directives to standard output. The result is either success with no changes for non-Windows builds, success after printing linker instructions for supported Windows toolchains, or an error if Cargo did not provide the crate directory.

Call relations: Cargo calls this function automatically while building the crate. The function asks the standard environment APIs for build settings and uses printed cargo: lines to hand instructions back to Cargo. Cargo then passes those instructions to the linker when building only the codex-windows-sandbox-setup binary.

Call graph: 4 external calls (from, var, var_os, println!).

fn main()

Purpose: This build-script entry point checks whether the current build target is macOS. If it is, it tells Cargo to add the -ObjC linker argument so macOS Objective-C code is linked correctly.

Data flow: It reads the CARGO_CFG_TARGET_OS environment variable, which Cargo sets to describe the target operating system. If that value is exactly macos, it prints a Cargo instruction to standard output. Cargo reads that printed line and changes the later compiler/linker command; otherwise, nothing is changed.

Call relations: Cargo runs this main function automatically as part of the build process. Inside it, the function asks the environment for the target operating system and, only for macOS, hands a linker instruction back to Cargo by printing it in Cargo’s expected format.

Call graph: 2 external calls (println!, var).

fn main()

Purpose: This is the entry point of the build script. It decides whether the samples folder exists and, if so, starts telling Cargo to watch it for changes.

Data flow: It begins with the fixed path src/assets/samples. If that path is missing, nothing else happens. If it exists, the function prints a Cargo instruction for that folder, then passes the folder path to visit_dir so every file and subfolder can also be registered for change tracking.

Call relations: Cargo runs main automatically before compiling the crate. main sets up the first watch instruction, then hands the deeper folder-walking work to visit_dir.

Call graph: calls 1 internal fn (visit_dir); 2 external calls (new, println!).

fn visit_dir(dir: &Path)

Purpose: This function walks through a folder and tells Cargo to rerun the build script if anything inside that folder changes. It also goes into nested folders so the watch list covers the whole sample tree.

Data flow: It receives a directory path. It tries to read the directory's contents; if that fails, it returns without making noise. For each readable entry, it prints a Cargo watch instruction for that path. If an entry is itself a directory, it repeats the same process inside that directory.

Call relations: It is called by main after the top-level samples folder has been found. From there, it continues recursively, meaning each folder can call visit_dir again for its own subfolders until all reachable sample paths have been announced to Cargo.

Call graph: called by 1 (main); 2 external calls (read_dir, println!).