Sidecar Runtimes ⚙️

---

Sidecar Runtimes ⚙️ Pre-Compiled Native Dependencies

This directory serves as 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.

Purpose and Structure

To create a truly portable and self-contained application, we cannot rely on the user having pre-installed runtimes like Node.js. Instead, we "vendor" these runtimes by downloading their official, standalone distributions and storing them here.

The directory is organized to allow for deterministic selection by our 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 in this directory is responsible for populating this structure. It fetches the official distributions for various sidecars and platforms and organizes them according to the convention above.

The download tool provides:

• Concurrent Downloads: Parallel downloading of multiple binaries using Tokio
• Intelligent Caching: Maintains a Cache.json file to track downloaded versions
• Version Resolution: Automatically resolves major versions to latest patch from nodejs.org
• Git LFS Management: Automatically updates .gitattributes for large binary tracking
• Platform Matrix: Supports multiple target triples (x86_64, aarch64 for macOS, Linux, Windows)

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 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.

Land	PlayForm	NLnet	NGI0 Commons Fund

---

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