SideCar

⚙️

+

Land

🏞️

---

SideCar ⚙️

Pre-Compiled Native Dependencies for Land 🏞️

SideCar is the central repository for all pre-compiled, platform-specific sidecar binaries required by the Land Code Editor ecosystem. A "sidecar" is a standalone executable that runs alongside the main Mountain application to provide specialized functionality, such as the Cocoon extension host 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 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).

How It's Used

The Download Rust binary populates this structure. It fetches 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.

---

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.

Running the Download Tool

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

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

---

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](.gitattributes) — Git LFS configuration for large binaries

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

---

Parent Project: Mountain | Related Directory: Binary

License ⚖️

This project is licensed under Creative Commons CC0.

See the LICENSE file for details.

---

Changelog 📜

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

---

Funding & Acknowledgements 🙏🏻

Code Editor Land is funded through the NGI0 Commons Fund, established by NLnet with financial support from the European Commission's Next Generation Internet programme, under grant agreement No. 101135429.

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