Skip to content

getting-started.md

Latest commit

 

History

History
99 lines (70 loc) · 2.25 KB

getting-started.md

File metadata and controls

99 lines (70 loc) · 2.25 KB
Raw

Getting Started

This guide helps you build and run CrossVi locally.

Prerequisites

  • PlatformIO Core (pio) or VS Code + PlatformIO IDE
  • Python 3.8+
  • clang-format 21+ in your PATH (CI uses clang-format 21)
  • USB-C cable
  • Xteink X3 or X4 device for hardware testing

If ./bin/clang-format-fix fails with either of these errors, install clang-format 21:

  • clang-format: No such file or directory
  • .clang-format: error: unknown key 'AlignFunctionDeclarations'

Examples:

# Debian/Ubuntu (try this first)
sudo apt-get update && sudo apt-get install -y clang-format-21

# If the package is unavailable, add LLVM apt repo and retry
wget https://apt.llvm.org/llvm.sh
chmod +x llvm.sh
sudo ./llvm.sh 21
sudo apt-get update
sudo apt-get install -y clang-format-21

# macOS (Homebrew)
brew install clang-format

Then verify:

clang-format-21 --version

The reported major version must be 21 or newer.

Clone and initialize

git clone --recursive https://github.com/tvhdc/crossvi
cd crossvi

If you already cloned without submodules:

git submodule update --init --recursive

Enable the repository-managed Git hooks (required once per clone):

git config core.hooksPath .githooks
chmod +x .githooks/pre-commit

Build

pio run

To run the firmware UI without a device, continue with the desktop simulator guide.

Flash

For a first CrossVi installation, follow the Web Flasher procedure in the README and continue only after Validate partition table succeeds. Do not use PlatformIO upload for that first installation: its ESP32 target writes the bootloader, partition table, otadata helper and application image rather than only the inactive OTA slot.

On a Developer Edition device whose USB access and matching CrossVi partition layout have already been verified, the normal development upload command is:

pio run --target upload

First checks before opening a PR

./bin/clang-format-fix
pio check --fail-on-defect low --fail-on-defect medium --fail-on-defect high
pio run

What to read next