Last Updated: October 2, 2025
Version: v0.0.2
This guide helps you resolve common issues when building, testing, or using FerrisScript.
Quick Links:
Windows Issues | macOS Issues | Linux Issues | Build Errors | Godot Integration | Runtime Errors
link.exe not found”Cause: Missing MSVC (Microsoft Visual C++) build tools required by Rust.
Solution:
Verify installation:
# Check if MSVC is available
where link.exe
# Should output something like:
# C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Tools\MSVC\...\bin\Hostx64\x64\link.exe
Rebuild FerrisScript:
cargo clean
cargo build
Alternative: Use GNU toolchain (not recommended for Godot compatibility)
windows_x86_64_msvc crate”Cause: Corrupted Rust toolchain or missing Windows target.
Solution:
Update Rust toolchain:
rustup update
Add Windows MSVC target (usually installed by default):
rustup target add x86_64-pc-windows-msvc
Clean and rebuild:
cargo clean
cargo build
Cause: Low memory, antivirus interference, or disk space issues.
Solution:
Close unnecessary applications - Cargo build is memory-intensive
target/ directory grows large during buildY:\cpark\Projects\RustyScript\targetUse fewer parallel jobs:
cargo build -j 2 # Limit to 2 parallel jobs
Cause: PowerShell execution policy or path issues.
Solution:
Check execution policy:
Get-ExecutionPolicy
If “Restricted”, allow scripts:
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
Verify Rust is in PATH:
echo $env:PATH | Select-String cargo
If not found, add manually:
sysdm.cplC:\Users\YOUR_USERNAME\.cargo\binCause: Missing Xcode Command Line Tools (required for compiling Rust on macOS).
Solution:
Install Xcode Command Line Tools:
xcode-select --install
Accept license agreement:
sudo xcodebuild -license accept
Verify installation:
xcode-select -p
# Should output: /Library/Developer/CommandLineTools
Rebuild FerrisScript:
cargo clean
cargo build
Alternative: Install full Xcode from App Store (larger download, includes more tools).
Cause: Incomplete or corrupted Xcode installation.
Solution:
Reinstall Command Line Tools:
sudo rm -rf /Library/Developer/CommandLineTools
xcode-select --install
Reset Xcode developer directory:
sudo xcode-select --reset
Clean and rebuild:
cargo clean
cargo build
cc failed”Cause: Incompatible SDK version or missing libraries.
Solution:
Check macOS SDK:
xcrun --show-sdk-path
Update Homebrew (if using):
brew update
brew upgrade
Install required libraries:
brew install llvm
Update Rust:
rustup update
Cause: macOS uses case-insensitive filesystem by default, but git preserves case.
Error Example:
cd ferrisscript # ERROR: No such file or directory
Solution:
Use the correct capitalization:
cd FerrisScript # Correct
Note: This was a bug in earlier README versions (fixed in v0.0.2).
cc failed” or “cannot find -lclang”Cause: Missing build essentials or libclang (required for gdext bindings).
Solution (Ubuntu/Debian):
sudo apt update
sudo apt install build-essential libclang-dev pkg-config
Solution (Fedora/RHEL):
sudo dnf install gcc clang-devel pkg-config
Solution (Arch Linux):
sudo pacman -S base-devel clang
Verify installation:
clang --version
pkg-config --version
gdext”Cause: Incompatible or missing libclang version.
Solution:
Install specific libclang version:
# Ubuntu/Debian
sudo apt install libclang-14-dev
# Fedora
sudo dnf install clang-devel
Set LIBCLANG_PATH environment variable:
export LIBCLANG_PATH=/usr/lib/llvm-14/lib
cargo build
Make permanent (add to ~/.bashrc or ~/.zshrc):
echo 'export LIBCLANG_PATH=/usr/lib/llvm-14/lib' >> ~/.bashrc
source ~/.bashrc
Cause: Case-sensitive filesystem + incorrect directory name.
Error:
cd ferrisscript # ERROR (lowercase)
Solution:
Use the correct capitalization:
cd FerrisScript # Correct (capital F and S)
Why? Linux filesystems are case-sensitive, unlike Windows. The repository name is FerrisScript.
Cause: Insufficient permissions or incorrect ownership.
Solution:
For build directory issues:
# Take ownership of target directory
sudo chown -R $USER:$USER target/
For cargo cache issues:
# Reset cargo permissions
sudo chown -R $USER:$USER ~/.cargo/
Never use sudo with cargo:
# DON'T do this:
sudo cargo build # ❌ Bad - creates permission issues
# Instead:
cargo build # ✅ Good
Cause: Rust version too old or rustup out of date.
Solution:
# Update Rust to latest stable
rustup update stable
# Verify version (need 1.70+)
rustc --version
# Should output: rustc 1.70.0 or higher
Cause: Missing dependencies or corrupted Cargo.lock.
Solution:
# Clean build artifacts
cargo clean
# Update dependencies
cargo update
# Rebuild
cargo build --workspace
If still failing:
Delete Cargo.lock and target directory:
rm Cargo.lock
rm -rf target/
cargo build
Check internet connection (cargo needs to download crates)
__getreent” (Windows)Cause: Conflict between MinGW and MSVC toolchains.
Solution:
Use MSVC toolchain consistently:
# Set default toolchain
rustup default stable-x86_64-pc-windows-msvc
# Remove MinGW if present
rustup toolchain uninstall stable-x86_64-pc-windows-gnu
# Rebuild
cargo clean
cargo build
gdextension_api in this scope”Cause: godot_bind crate has dependency issues with gdext.
Solution:
Clean rebuild:
cargo clean
cargo build --package ferrisscript_godot_bind
Update gdext dependency (if on main branch):
cargo update -p gdext
If still failing, check gdext compatibility:
Symptoms:
cargo test # Some tests fail
Solution:
Check if specific crate has issues:
cargo test --package rustyscript_compiler # Test compiler only
cargo test --package rustyscript_runtime # Test runtime only
Run with backtrace for details:
RUST_BACKTRACE=1 cargo test
Check test output:
cargo test -- --nocapture # Show println! output
Report bug if tests fail on clean install:
rustc --versionNote: Godot integration testing is partially deferred in v0.0.1. Full automation planned for v0.0.3+. See FUTURE_AUTOMATION.md.
.gdextension fileSymptoms:
.ferris scripts don’t appear in GodotSolution:
Verify .gdextension file location:
godot_test/addons/ferrisscript/ferrisscript.gdextension
Check .gdextension syntax:
[configuration]
entry_symbol = "gdext_rust_init"
[libraries]
linux.x86_64 = "res://addons/ferrisscript/bin/libferrisscript_godot_bind.so"
macos.x86_64 = "res://addons/ferrisscript/bin/libferrisscript_godot_bind.dylib"
windows.x86_64 = "res://addons/ferrisscript/bin/ferrisscript_godot_bind.dll"
Verify library file exists:
# Linux
ls godot_test/addons/ferrisscript/bin/*.so
# macOS
ls godot_test/addons/ferrisscript/bin/*.dylib
# Windows
dir godot_test\addons\ferrisscript\bin\*.dll
Restart Godot editor - GDExtensions load at startup
Check Godot version - Must be 4.2 or later
Godot → Help → About
Cause: Library built for wrong platform or architecture.
Solution:
Verify your platform:
rustc --version --verbose
# Look for "host:" line
Build for correct target:
# Linux
cargo build --package ferrisscript_godot_bind --target x86_64-unknown-linux-gnu
# macOS
cargo build --package ferrisscript_godot_bind --target x86_64-apple-darwin
# Windows
cargo build --package ferrisscript_godot_bind --target x86_64-pc-windows-msvc
Rebuild and replace library:
cargo build --package ferrisscript_godot_bind --release
# Copy from target/release/ to godot_test/addons/ferrisscript/bin/
.ferris scripts cause Godot to crashSymptoms:
Possible Causes:
Solution:
println! statements in your .ferris fileTest script in isolation:
cargo run --bin rustyscript_runtime your_script.ferris
Simplify script to minimal reproduction:
fn main() {
println!("Hello"); // Start simple
}
Check Godot console for error messages
.ferris script, Godot versionSymptoms:
.ferris script with a type error (e.g., @export let mut health: i32 = "Banana";).ferris scriptExample Error:
ERROR: crates\godot_bind\src\lib.rs:719 - Failed to compile script 'res://scripts/inspector_minimal.ferris': Error[E200]: Type mismatch
ERROR: Type mismatch in global variable 'health': expected i32, found String at line 1, column 1
ERROR:
ERROR: 1 | @export let mut health: i32 = "Banana";
ERROR: | ^ Value type String cannot be coerced to i32
Then switching scripts:
Set script_path
📝 Script path changed: res://scripts/inspector_minimal.ferris → res://scripts/other_script.ferris
Cause: When a script fails to compile, the property list isn’t cleared. Switching to a new script doesn’t trigger property list refresh if the old script left the node in an error state.
Solution (Workaround):
Fix type errors before switching scripts
// ✅ Correct
@export let mut health: i32 = 100;
Status: Known issue in v0.0.4. Will be fixed in v0.0.5 by:
notify_property_list_changed() even on error pathsload_script()Workaround Impact: Low - only affects development workflow when fixing type errors.
.ferris scriptExample:
Error: Expected type i32, found f32
Cause: Type checker caught an error (working as intended).
Solution:
Fix type in your .ferris file:
// ❌ Wrong
let x: i32 = 3.14; // Error: f32 assigned to i32
// ✅ Correct
let x: f32 = 3.14; // Explicit f32
// or
let x = 3; // Integer literal (i32 by default)
Cause: Variable not declared or scope issue.
Solution:
Check variable declaration:
// ❌ Wrong - variable used before declaration
fn main() {
println!(x); // Error: unknown identifier 'x'
let x = 5;
}
// ✅ Correct
fn main() {
let x = 5;
println!(x);
}
Debugging steps:
Add println! statements:
fn calculate(x: i32) -> i32 {
println!("Input: {}", x); // Debug
let result = x * 2;
println!("Result: {}", result); // Debug
result
}
Run tests:
cargo test
i32 → f32 works (automatic)f32 → i32 requires explicit cast (not supported in v0.0.1)Verify operator precedence:
let x = 2 + 3 * 4; // Result: 14 (not 20)
cargo clean && cargo buildrustup updateWhen reporting issues, include:
rustc --version)Error message: Copy full error output
Steps to reproduce: Minimal example that triggers the issue
Expected vs actual behavior
.ferris file or build commandMade with 🦀 and ❤️ for the Godot community