Skip to content

Commit 74292f5

Browse files
NikolaRHristovNikolaRHristov
committed
1 parent 26b8342 commit 74292f5

1 file changed

Lines changed: 123 additions & 0 deletions

File tree

‎Documentation/GitHub/DeepDive.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
# SideCar — Deep Dive
2+
3+
This document provides the technical foundation for the SideCar binary
4+
distribution layer within the Land ecosystem. **SideCar** manages pre-compiled,
5+
platform-specific runtime binaries (primarily Node.js) so that the Land editor
6+
can bundle vendored runtimes without requiring users to install them separately.
7+
8+
---
9+
10+
## Architecture
11+
12+
SideCar is a Rust workspace containing a download tool and a spawn helper. The
13+
download tool fetches official runtime distributions and organizes them under a
14+
target-triple directory convention. The spawn helper is used by Mountain to
15+
launch sidecars from the vendored binary store.
16+
17+
```mermaid
18+
graph TB
19+
subgraph "SideCar — Binary Distribution"
20+
DownloadBin["Source/Download.rs\nDownload binary entry"]
21+
SpawnBin["Source/Spawn.rs\nSpawn helper binary"]
22+
LibraryRS["Source/Library.rs\nShared library"]
23+
CacheJSON["Cache.json\nVersion tracking"]
24+
GitAttributes[".gitattributes\nGit LFS configuration"]
25+
end
26+
27+
subgraph "External Sources"
28+
NodeJSOrg["nodejs.org\nOfficial Node.js distributions"]
29+
OtherRuntimes["Other Runtime Sources"]
30+
end
31+
32+
subgraph "Directory Structure"
33+
TargetTriple["[target-triple]/\ne.g. aarch64-apple-darwin"]
34+
RuntimeName["[SIDECAR_NAME]/\ne.g. NODE"]
35+
Version["[version]/\ne.g. 22"]
36+
Bin["bin/node"]
37+
end
38+
39+
subgraph "Consumers"
40+
Mountain["Mountain\nbuild.rs selects binary"]
41+
Tauri["Tauri\nbundles binary in installer"]
42+
end
43+
44+
DownloadBin --> CacheJSON
45+
DownloadBin --> GitAttributes
46+
NodeJSOrg --> DownloadBin
47+
OtherRuntimes --> DownloadBin
48+
DownloadBin --> TargetTriple
49+
TargetTriple --> RuntimeName
50+
RuntimeName --> Version
51+
Version --> Bin
52+
TargetTriple --> Mountain
53+
Mountain --> Tauri
54+
```
55+
56+
---
57+
58+
## Key Modules
59+
60+
| Path | Description |
61+
| :--- | :--- |
62+
| `Source/Download.rs` | Main download binary: fetches runtime distributions, resolves versions, organizes by target triple |
63+
| `Source/Spawn.rs` | Spawn helper: invoked by Mountain to launch a sidecar binary from the vendored store |
64+
| `Source/Library.rs` | Shared library code: version resolution utilities, path helpers, cache types |
65+
| `Source/Source/` | Internal module source files for the library |
66+
| `Cache.json` | Tracks which versions have been downloaded per target triple to avoid redundant fetches |
67+
| `.gitattributes` | Configured by the download tool to register large binary files with Git LFS |
68+
69+
---
70+
71+
## Data Flow
72+
73+
```mermaid
74+
sequenceDiagram
75+
participant Developer as Developer / CI
76+
participant DownloadTool as Download Binary
77+
participant NodeJSOrg as nodejs.org
78+
participant Cache as Cache.json
79+
participant Store as SideCar Directory
80+
81+
Developer->>DownloadTool: ./Target/release/Download
82+
DownloadTool->>Cache: Read existing versions
83+
DownloadTool->>NodeJSOrg: GET /dist/index.json (version manifest)
84+
NodeJSOrg->>DownloadTool: Latest patch for major version 22
85+
DownloadTool->>NodeJSOrg: GET /dist/v22.x.y/node-v22.x.y-darwin-arm64.tar.gz
86+
NodeJSOrg->>DownloadTool: Binary archive
87+
DownloadTool->>Store: Extract to aarch64-apple-darwin/NODE/22/bin/node
88+
DownloadTool->>Cache: Write Cache.json (version locked)
89+
DownloadTool->>Store: Update .gitattributes for Git LFS tracking
90+
```
91+
92+
**Build-time selection:**
93+
94+
Mountain's `build.rs` reads the SideCar directory, selects the binary matching
95+
the current Tauri build target triple, and copies it into the Tauri `sidecar`
96+
resource path for bundling into the application installer.
97+
98+
---
99+
100+
## Integration Points
101+
102+
| Connecting Element | Direction | Mechanism | Description |
103+
| :--- | :--- | :--- | :--- |
104+
| **Mountain** | Consumer | `build.rs` file copy | Mountain's build script selects the correct Node.js binary by target triple |
105+
| **Tauri** | Consumer | Sidecar resource bundling | Tauri bundles the selected binary into the platform installer |
106+
| **Cocoon** | Runtime dependency | Spawned process | Mountain spawns Cocoon using the vendored Node.js binary from the SideCar store |
107+
| **Air** | Potential consumer | Same convention | Additional daemon binaries may be vendored using the same target-triple structure |
108+
109+
---
110+
111+
## Configuration
112+
113+
| Parameter | Convention / Value | Description |
114+
| :--- | :--- | :--- |
115+
| Directory structure | `[target-triple]/[NAME]/[version]/bin/` | Standard layout for deterministic build-time binary selection |
116+
| Target triples | `x86_64-pc-windows-msvc`, `aarch64-apple-darwin`, `x86_64-unknown-linux-gnu`, etc. | All Tauri-supported platform identifiers |
117+
| Node.js major version | `22` (current default) | Controlled by the `--node-version` build flag |
118+
| Cache file | `Cache.json` | JSON map of `{ "[triple]/[name]/[major]": "[resolved-version]" }` |
119+
| Git LFS | `.gitattributes` auto-updated | All `*.node`, `node`, `node.exe` binaries tracked via LFS |
120+
121+
The SideCar directory is not committed to version control in its populated
122+
form. Developers run the Download tool once during initial project setup, and
123+
CI environments run it as part of the release pipeline.

0 commit comments

Comments
 (0)