Skip to content

Commit 96557ef

Browse files
AIdrifterAIdrifter
committed
docs: add platforms overview index and custom evergreen setup guide
Add a single centralized overview index (site/docs/development/index.md) providing: - A comparison matrix of supported platforms (Linux, Android TV, RDK, Docker tooling). - A 3-stage recommended development workflow. - Custom Evergreen path configurations and parameter mapping reference table for SoC partners. - Step-by-step guide for SoC partners to build and compress custom debug Cobalt Core packages locally using host lz4_compress. Bug: 537982944
1 parent 1c66a9a commit 96557ef

1 file changed

Lines changed: 120 additions & 0 deletions

File tree

‎cobalt/site/docs/development/index.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
Project: /youtube/cobalt/_project.yaml
2+
Book: /youtube/cobalt/_book.yaml
3+
4+
# Development & Build Platforms Overview
5+
6+
Welcome to Cobalt Development! Cobalt supports multiple operating systems, hardware architectures, and build host environments.
7+
8+
This guide provides an overview of the supported platforms, their target hardware, intended use cases, and recommended development workflows.
9+
10+
---
11+
12+
## Supported Build Platforms & Setup Guides
13+
14+
| Platform / Tooling | Type | Target Architecture & Hardware | Primary Purpose & Intended Use | Setup Guide |
15+
| :--- | :--- | :--- | :--- | :--- |
16+
| **Linux** | Target OS | **x86_64 Desktop** (Ubuntu / X11 / Wayland) | **Developer Workstation Environment**. Provides the fastest compile-and-debug iteration cycle for core logic, Web APIs, and Starboard verification (`nplb`), without requiring embedded TV hardware. | [setup-linux.md](setup-linux.md) |
17+
| **Android TV (ATV)** | Target OS | **ARM / ARM64 / x86** (Smart TVs, Streaming Sticks) | **Android TV Production Target**. Compiles native engine (`libchrobalt.so`) and packages into standard Android application package (`Cobalt.apk`, `dev.cobalt.coat`). | [setup-android.md](setup-android.md) |
18+
| **RDK** | Target OS | **ARM / ARM64** (Pay-TV Set-Top Boxes, STB reference hardware) | **Pay-TV & STB Platform Target**. Integrates Starboard for RDK (`evergreen-arm-hardfp-rdk`) for operator-managed set-top box deployments. | [setup-rdk.md](setup-rdk.md) |
19+
| **Docker** | Host Tooling | **Linux x86_64 Host** (Containerized Builder) | **Build Environment Consistency**. Containerized build host tool that standardizes dependencies and tools across developer workstations to avoid host OS version conflicts. | [setup-docker.md](setup-docker.md) |
20+
21+
---
22+
23+
## Recommended Development Workflow
24+
25+
To maximize development efficiency, we recommend following a 3-stage development workflow:
26+
27+
1. **Stage 1: Core Logic & Web Feature Development**
28+
- **Platform**: `Linux` (`linux-x64x11`)
29+
- **Why**: Fastest build times, direct gdb/lldb integration, and immediate execution on your workstation. Run `nplb` to verify Starboard API compliance.
30+
31+
2. **Stage 2: Standardized Host Build Environment**
32+
- **Tooling**: `Docker`
33+
- **Why**: Use containerized build definitions to build for cross-compiled targets (like RDK or Android) without polluting or conflicting with your local host environment.
34+
35+
3. **Stage 3: Target Device & Media Integration Validation**
36+
- **Platform**: `Android TV` or `RDK`
37+
- **Why**: Final testing of hardware video/audio decoding, platform lifecycle (suspend/resume), remote control input handling, and system-level performance.
38+
39+
---
40+
41+
## Core Compilation & Debug Verification: Evergreen vs. Native APK
42+
43+
When developing, debugging, or verifying custom Cobalt modifications on device hardware, developers and SoC partners must distinguish between Cobalt's two fundamentally different runtime architectures. Build targets, compression steps, and library replacement procedures differ substantially across platforms:
44+
45+
| Feature / Step | Evergreen Architecture (RDK / Linux) | Native APK Architecture (Android TV) |
46+
| :--- | :--- | :--- |
47+
| **Target Architecture** | **Evergreen Dynamic Slot** (`use_evergreen = true`) | **Standard Android Application** (`use_evergreen = false`) |
48+
| **Primary Build Target** | **`cobalt`** and **`lz4_compress`** | **`cobalt_apk`** |
49+
| **Compiled Artifacts** | `app/cobalt/lib/libcobalt.so` and `libcobalt.lz4` | `apks/Cobalt.apk` (`dev.cobalt.coat`, bundling `libchrobalt.so`) |
50+
| **Debug & Verification** | **Direct Slot Replacement**. Unpack the CRX or access Slot 0 on device, and overwrite `libcobalt.so` (or `.lz4`) via SSH/SCP or `deploy_rdk.py --only-lib`. | **Full APK Reinstallation**. Do not modify filesystem shared libraries directly; reinstall the updated package via `adb install -r -d Cobalt.apk`. |
51+
| **Host Compression** | Required when testing production compressed library loading (`lz4_compress`). | **Not used / Inapplicable**. Native packaging directly handles shared library compression in APK. |
52+
53+
> [!IMPORTANT]
54+
> **Live Replacement Safety Rules for Evergreen Platforms:**
55+
> When replacing shared libraries (`libcobalt.so` or `libcobalt.lz4`) directly on live RDK or Linux target hardware:
56+
> 1. **Stop Active Processes First**: Kill running `loader_app` or WPEFramework `YouTube` sessions before copying new files. Overwriting active mapped libraries without stopping the process causes immediate `Text file busy` failures or fatal kernel segmentation faults.
57+
> 2. **Deploy Both Formats**: When testing unstripped builds, deploy both uncompressed (`.so`) and compressed (`.lz4`) library files simultaneously to avoid loader magic signature parsing exceptions.
58+
> 3. **Keep Resources Synchronized**: If your modifications change interface definitions or resources, always push updated `content/` resources (`cobalt_shell.pak`) alongside the library binary.
59+
60+
---
61+
62+
## Custom Evergreen Setup, Path Configurations & Debugging for SoC Partners
63+
64+
When deploying prebuilt or custom-built Evergreen packages (unzipped CRX packages) onto target Linux/ARM hardware, configure the following path parameters and environment variables.
65+
66+
### 1. Evergreen Path Parameter Mapping Reference
67+
68+
| Parameter / Variable | Category | Expected Target Path | Description |
69+
| :--- | :--- | :--- | :--- |
70+
| **`--evergreen_library`** | `elf_loader_sandbox` Switch | `<target_root>/app/cobalt/lib/libcobalt.so` (or `libcobalt.lz4`) | Points to the Cobalt Core shared library binary. |
71+
| **`--evergreen_content`** | `elf_loader_sandbox` Switch | `<target_root>/app/cobalt/content` | Points to the web engine resource directory containing `cobalt_shell.pak`, `fonts/`, and `ssl/`. |
72+
| **`--content`** | `loader_app` Switch | `<target_root>` | Overrides the base root directory for `kSbSystemPathContentDirectory`. `loader_app` will append `/app/cobalt/` to locate Slot 0. |
73+
| **`kSbSystemPathContentDirectory`** | Starboard System Path API | `<target_root>` | Returned by `SbSystemGetPath()`. Used by `loader_app` to construct paths for `manifest.json`, `lib/`, and `content/`. |
74+
75+
#### Example Target Directory Structure (Slot 0 Layout):
76+
```text
77+
/usr/share/content/data/ <-- Base Target Root (<target_root>)
78+
├── loader_app <-- Partner-built Loader executable
79+
├── elf_loader_sandbox <-- Sandbox test executable
80+
└── app/
81+
└── cobalt/ <-- Factory Slot 0 Directory
82+
├── manifest.json <-- Evergreen manifest file
83+
├── lib/
84+
│ └── libcobalt.so <-- Core shared library
85+
└── content/
86+
├── cobalt_shell.pak <-- UI and web resources
87+
├── fonts/ <-- System fonts and fonts.xml
88+
└── ssl/ <-- Root CA certificates
89+
```
90+
91+
### 2. Compiling Custom Debug CRX / Core Packages for SoC Partners
92+
93+
SoC Partners and OEMs can compile custom Cobalt Core packages with full debugging symbols enabled to inspect C++ stack traces on partner hardware:
94+
95+
1. **Initialize GN for Debug / Devel Build**:
96+
```bash
97+
cobalt/build/gn.py -p <platform> -c devel --no-rbe
98+
```
99+
*(e.g., `-p evergreen-arm-hardfp` for 32-bit ARM, or `-p evergreen-arm64` for 64-bit ARM)*
100+
101+
2. **Compile Uncompressed Cobalt Core & Resources**:
102+
```bash
103+
autoninja -C out/<platform>_devel cobalt lz4_compress
104+
```
105+
This generates the uncompressed debug shared library (`out/<platform>_devel/app/cobalt/lib/libcobalt.so`), resource files, and the host compression tool. Note that specifying `cobalt lz4_compress` directly targets the Core library and compression binary, avoiding extraneous wrapper target compilation.
106+
107+
3. **(Optional) Compress Library for Production Testing**:
108+
To test LZ4 compressed library loading (`libcobalt.lz4`), run Cobalt's host compression tool:
109+
```bash
110+
out/<platform>_devel/clang_x64/lz4_compress \
111+
out/<platform>_devel/app/cobalt/lib/libcobalt.so \
112+
out/<platform>_devel/app/cobalt/lib/libcobalt.lz4
113+
```
114+
115+
---
116+
117+
## Additional References
118+
119+
- [Supported Features](reference/supported-features.md)
120+
- [Troubleshooting Guide](reference/troubleshooting.md)

0 commit comments

Comments
 (0)