In Xcode, what does ENABLE_USER_SCRIPT_SANDBOXING change for a Run Script build phase, and why must the script declare its input and output files?
answer
- undeclared reads and writes
- Input Files, Output Files, .xcfilelist
- SCRIPT_INPUT_FILE_0 and friends
- Xcode 15 flipped the default to YES
- a Sandbox deny file-read-data error
basics
~20 sWith ENABLE_USER_SCRIPT_SANDBOXING on, Xcode sandboxes Run Script phases to disallow undeclared input and output dependencies, so reading an unlisted project file fails. Declared files also let Xcode order the script and skip it when nothing changed.
solid answer
~40 sA **Run Script** phase runs a shell script as one step of a target's build. Its **Input Files** and **Output Files** (paths or `.xcfilelist` files) tell the build system what the script depends on and produces; Xcode exposes them as `SCRIPT_INPUT_FILE_0`, `SCRIPT_OUTPUT_FILE_0` and so on. With them, Xcode orders the script against concurrent tasks and runs it only when needed; without them it runs on every build and can introduce incorrect builds. `ENABLE_USER_SCRIPT_SANDBOXING` enforces the declaration: the build system sandboxes user scripts to disallow undeclared input and output dependencies, so a script that reads an unlisted project file fails with a sandbox deny error. Since Xcode 15 the setting defaults to YES. The fix is to declare the files; turning the setting off for that target is the escape hatch.
code
bash · 16 lines# Run Script phase of the meal-kit app target.
# Input Files: $(SRCROOT)/Config/build-info.template.json
# Output Files: $(TARGET_BUILD_DIR)/$(UNLOCALIZED_RESOURCES_FOLDER_PATH)/build-info.json
set -euo pipefail
template="${SCRIPT_INPUT_FILE_0}"
output="${SCRIPT_OUTPUT_FILE_0}"
if [ ! -f "$template" ]; then
echo "error: build-info template is missing"
exit 1
fi
sed -e "s/__CONFIGURATION__/${CONFIGURATION}/" \
-e "s/__BUILD__/${CURRENT_PROJECT_VERSION}/" \
"$template" > "$output"go deeper
Know where Run Script phases live in a target's Build Phases tab and that a nonzero exit status fails the build.
Explain Input and Output Files, the SCRIPT_INPUT_FILE variables, and what the sandbox denies once ENABLE_USER_SCRIPT_SANDBOXING is on.
Diagnose a script that broke after an Xcode upgrade, declare its real dependencies, and limit any opt-out to the one target that needs it.
Set a rule that every build script declares its files and runs sandboxed, and decide how exceptions are reviewed and retired.
## What a Run Script phase is A target's **build phases** are the steps Xcode runs to make its product: Compile Sources, Link Binary With Libraries, Copy Bundle Resources, Copy Files phases (one of which Xcode titles **Embed Frameworks**) and any number of **Run Script** phases. A Run Script phase runs a shell script you type into the phase or drag in. Typical uses are stamping build information into the bundle, converting a resource into a faster format, or running a code-quality tool (how a particular linter or formatter is wired in is covered with those tools). Xcode runs the script with the same build settings and environment variables as the target, so `CONFIGURATION`, `SRCROOT`, `TARGET_BUILD_DIR` and `CURRENT_PROJECT_VERSION` are all readable. Dragging phases changes their listed order, but Xcode still executes tasks according to dependency order. ## Declaring inputs and outputs The phase has two lists, **Input Files** and **Output Files**, each holding paths (build variables allowed, such as `$(SRCROOT)/Config/build-info.template.json`) or `.xcfilelist` files that hold one path per line. Xcode turns them into environment variables: - `SCRIPT_INPUT_FILE_COUNT` and `SCRIPT_INPUT_FILE_0`, `SCRIPT_INPUT_FILE_1`, ... - `SCRIPT_OUTPUT_FILE_COUNT` and `SCRIPT_OUTPUT_FILE_0`, ... - the matching `SCRIPT_INPUT_FILE_LIST_*` and `SCRIPT_OUTPUT_FILE_LIST_*` variables for file lists. Apple's documentation gives the reason for the lists: Xcode needs the set of files a script accesses so that it runs scripts and other concurrently executing tasks in the right order, and runs the script only when necessary. If you leave them empty, Xcode runs the script on every build, and it might introduce incorrect build behaviour, for example a later task reading a file the script has not finished writing. ## What sandboxing adds `ENABLE_USER_SCRIPT_SANDBOXING` (User Script Sandboxing) is described in the build settings reference in one line: when enabled, the build system sandboxes user scripts to disallow undeclared input and output dependencies. In practice: 1. A script may read the files in its Input Files and write the files in its Output Files. 2. Reading another project file, such as a config file in the repository nobody listed, is denied by the sandbox, and the build fails with an error naming the tool, the word Sandbox and the denied operation, for example a deny on file-read-data. 3. The phase's dependency information is now trustworthy, because a script physically cannot depend on a file it did not declare. Xcode 15 changed the setting's default from NO to YES, which is why many older scripts started failing after an upgrade: they had always read undeclared files and nothing had checked. ## Fixing a failing script - **Preferred**: add every file the script reads to Input Files and every file it writes to Output Files, using an `.xcfilelist` when the list changes often. - **Escape hatch**: set `ENABLE_USER_SCRIPT_SANDBOXING = NO` for that one target, and record why. You lose both the protection and the guarantee that the phase's dependencies are complete. - A script that legitimately must run on every build can have **Based on dependency analysis** unticked, which runs it on every incremental build and suppresses the warning about unspecified outputs. ## When a Run Script phase is the wrong tool - **A build rule** fits better when a script compiles or converts each input file of one type into another format; Apple's guide suggests a custom build rule for that case, so Xcode processes each matching file as part of the build. - **A scheme pre-action or post-action** runs a script before or after a scheme action such as Build or Test. Unlike a build phase, it runs only when you choose that command from the Product menu, so it suits setup that is not part of producing the product. - **A package plugin** is the other route for tools distributed as Swift packages; how those plugins are sandboxed is covered with Swift Package Manager plugins. ## Reporting from the script The build log understands lines of the form `file:line: error: message`, with `warning:` and `note:` too; the file and line are optional. A nonzero exit status fails the build. The example script below does both when its declared template is missing. | Want | Do | |---|---| | fail the build | print `error: ...` and `exit 1` | | warn without failing | print `warning: ...` and exit 0 | | run only when inputs change | declare inputs and outputs | | run on every build | untick Based on dependency analysis |
- Why not just set ENABLE_USER_SCRIPT_SANDBOXING to NO for the whole project?It makes the error go away by removing the check. Scripts can then depend on undeclared files again, so incremental builds can skip a script that should rerun or run it in the wrong order. Turning it off per target, for a tool that cannot declare its reads, keeps the protection everywhere else.
- When would you choose an .xcfilelist instead of listing paths in the phase?When the set of files changes often or is long, such as every JSON file in a resources folder. The file list is a text file with one path per line, it can be reviewed in a pull request, and build variables such as `$(SRCROOT)` work inside it.
- Sandboxing only stops scripts from reaching the network
- Listing input files is optional documentation with no effect
- A script fails the build by printing warning: and exiting 0
- Phase order in the editor is the order Xcode runs tasks
- Turning sandboxing off project-wide is the standard fix
Assumes Xcode 27; Xcode 15 changed the default of ENABLE_USER_SCRIPT_SANDBOXING from NO to YES.