SideCar

⚙️

+

Land

🏞️

---

SideCar ⚙️

Pre-Compiled Native Dependencies for Land 🏞️

VS Code ships one Node.js binary and detects the platform at runtime, with fallback chains that fail in edge cases (Alpine Linux, custom glibc versions, ARM configurations).

"The right Node.js binary. Compiled in. No detection."

SideCar packages the exact Node.js binary for each target triple at compile time: aarch64-apple-darwin, x86_64-pc-windows-msvc, and four others. Cocoon always gets the binary that matches the host. No runtime detection, no fallback chains, no surprises.

Welcome to SideCar, the central repository for all pre-compiled, platform-specific sidecar binaries required by the Land Code Editor ecosystem. A "sidecar" is an external, standalone executable that runs alongside the main Mountain application to provide specialized functionality, such as the Cocoon extension host which runs on Node.js.

SideCar is engineered to:

1. Provide Portable Runtimes: Vendored Node.js and other runtimes eliminate user dependency requirements.
2. Enable Deterministic Builds: Organized by target triple for build-time binary selection.
3. Support Multiple Platforms: Comprehensive matrix for macOS, Linux, and Windows on x86_64 and aarch64 architectures.
4. Automate Download Management: Automated fetching, caching, and Git LFS management of runtime binaries.

---

Directory Structure 📁

The SideCar directory is organized to allow for deterministic selection by the build system:

SideCar/
└── [target-triple]/
    └── [SIDECAR_NAME]/
        └── [version]/
            ├── bin/
            │   └── node
            ├── node.exe
            └── ... (other files from the distribution)

• [target-triple]: The platform-specific identifier used by Rust/Tauri (e.g., x86_64-pc-windows-msvc, aarch64-apple-darwin). This allows the build system to find the correct binary for the target platform.
• [SIDECAR_NAME]: The name of the runtime (e.g., NODE).
• [version]: The major version number of the runtime (e.g., 22).

Supported Target Triples

Target Triple	Platform
aarch64-apple-darwin	macOS Apple Silicon
x86_64-apple-darwin	macOS Intel
x86_64-pc-windows-msvc	Windows x64
aarch64-pc-windows-msvc	Windows ARM64
x86_64-unknown-linux-gnu	Linux x64 (glibc)
aarch64-unknown-linux-gnu	Linux ARM64 (glibc)

How It's Used

The Download Rust binary is responsible for populating this structure. It fetches the official distributions for various sidecars and platforms and organizes them according to the convention above.

During the application build, the main Build.rs orchestrator uses this repository as a source. Based on build flags (e.g., --node-version=22), it selects the appropriate executable from this directory and prepares it for bundling into the final application installer.

---

Key Features 🔐

• Concurrent Downloads: Parallel downloading of multiple runtime binaries using Tokio for maximum throughput.
• Intelligent Caching: Maintains a Cache.json file to track downloaded versions and avoid redundant downloads.
• Version Resolution: Automatically resolves major versions to latest patch from nodejs.org and other sources.
• Git LFS Management: Automatic .gitattributes updates for large binary tracking in Git LFS.
• Platform Matrix: Comprehensive support for x86_64 and aarch64 architectures across macOS, Linux, and Windows.

---

Core Architecture Principles 🏗️

Principle	Description	Key Components Involved
Deterministic Selection	Organize binaries by target triple for deterministic build-time selection.	Directory structure, target triple convention
Version Tracking	Maintain cache metadata to avoid redundant downloads and ensure version consistency.	Cache.json, version resolution
Git LFS Integration	Automatically manage Git LFS pointers for large binary tracking.	.gitattributes management

---

SideCar in the Land Ecosystem ⚙️ + 🏞️

Component	Role & Key Responsibilities
Download Tool	Populates the SideCar directory with pre-compiled runtime binaries.
Cache Manager	Tracks downloaded versions in Cache.json for build reproducibility.
Build Source	Provides vendored runtimes to Mountain during the build process.

---

System Architecture Diagram 🏗️

This diagram illustrates how SideCar vendors and organizes runtime dependencies.

graph LR
classDef sidecar fill:#f9f,stroke:#333,stroke-width:2px;
classDef external fill:#ddd,stroke:#666,stroke-dasharray: 5 5;
classDef storage fill:#9cf,stroke:#333,stroke-width:1px;

subgraph "External Sources"
NodeJSOrg["nodejs.org"]:::external
OtherRuntimes["Other Runtime Sources"]:::external
end

subgraph "SideCar ⚙️ (Download Tool)"
DownloadBin["Download Binary"]:::sidecar
CacheJSON["Cache.json"]:::sidecar
GitLFS[".gitattributes (LFS)"]:::sidecar

DownloadBin --> CacheJSON
DownloadBin --> GitLFS
end

subgraph "SideCar Directory Structure"
TargetTriple["[target-triple]/"]:::storage
RuntimeName["[SIDECAR_NAME]/"]:::storage
Version["[version]/bin/"]:::storage

TargetTriple --> RuntimeName
RuntimeName --> Version
end

NodeJSOrg --> DownloadBin
OtherRuntimes --> DownloadBin
DownloadBin --> TargetTriple

Loading

---

Deep Dive & Component Breakdown 🔬

To understand how SideCar's download tool works, see the following source files:

• Source/Download.rs - Main download binary entry point
• Cache.json - Download cache tracking file
• .gitattributes - Git LFS configuration for large binaries

The download tool handles concurrent downloads via Tokio, version resolution from nodejs.org, and automatic Git LFS management for tracking large binary files.

---

Getting Started 🚀

Running the Download Tool

# Build the download tool
cd Element/SideCar
cargo build --release

# Run to download and organize all sidecars
./Target/release/Download

Key Dependencies:

• tokio: Async runtime for concurrent downloads
• reqwest: HTTP client for fetching binaries
• serde/serde_json: Cache.json serialization
• git2: Git LFS management

Usage Pattern 🚀

The SideCar directory is populated once during project setup:

1. Build Download Tool: Compile the Download binary
2. Run Download: Execute to fetch and organize all runtime binaries
3. Build Mountain: The build system selects appropriate binaries from SideCar

[!NOTE] The contents of this directory are generated by the Download Rust binary and consist of large, third-party binaries. This directory should not be committed to version control and should be added to the project's .gitignore file. The tool should be run once to vendor the dependencies as part of the initial project setup.

---

Parent Project: Mountain | Related Directory: Binary

---

See Also

• SideCar Documentation
• Architecture Overview
• Why Rust
• Cocoon
• Mountain

---

License ⚖️

This project is released into the public domain under the Creative Commons CC0 Universal license. You are free to use, modify, distribute, and build upon this work for any purpose, without any restrictions. For the full legal text, see the LICENSE file.

---

Changelog 📜

Stay updated with our progress! See CHANGELOG.md for a history of changes specific to SideCar.

---

Funding & Acknowledgements 🙏🏻

SideCar is a core element of the Land ecosystem. This project is funded through NGI0 Commons Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet program. Learn more at the NLnet project page.

The project is operated by PlayForm, based in Sofia, Bulgaria.

PlayForm acts as the open-source steward for Code Editor Land under the NGI0 Commons Fund grant.

Land	PlayForm	NLnet	NGI0 Commons Fund

---

Project Maintainers: Source Open (Source/Open@Editor.Land) | GitHub Repository | Report an Issue | Security Policy