Set up development

Get the source

Install Git, Rustup, and just. Use the native build tools for your operating system. On macOS, install the Xcode Command Line Tools. On Windows, install the Visual Studio C++ build tools.

If you do not have repository write access, create a GitHub fork. Use your fork URL in the clone command below.

1. Clone the repository.
2. Open its root directory.

git clone https://github.com/EdwinZhanCN/LumilioCL.git
cd LumilioCL

Create a branch for the change. For the prefix, see Branches and merges:

git switch -c fix/<change-name>

Install the toolchain specified in rust-toolchain.toml:

rustup toolchain install

The repository specifies the development toolchain. Do not replace it with a different Rust version.

Prepare Linux libraries

The Linux CI job uses these packages:

sudo apt-get update
sudo apt-get install -y --no-install-recommends \
  build-essential clang cmake pkg-config \
  libssl-dev libzstd-dev libfontconfig-dev libfreetype-dev \
  libvulkan-dev libwayland-dev libxkbcommon-dev libxkbcommon-x11-dev \
  libx11-dev libx11-xcb-dev libxcb1-dev

A desktop session and graphics drivers are necessary to run the launcher. See the CI workflow for the current package list.

Run the launcher

From the repository root, run:

cargo run -p lumilio-app

Use a disposable data directory for manual tests. Set LUMILIO_HOME to that directory before you start the application. Do not use important game data for a destructive test.

Set the CurseForge API key

The CurseForge content source reads the CF_API_KEY environment variable when you build it. Without a key, that source is off by default. All other functions operate normally. Release builds get the key from a repository secret.

For local development, put the key in your user-level ~/.cargo/config.toml:

[env]
CF_API_KEY = 'your-key'

Use single quotes. They keep each $ in the key as it is. Do not put the key in the .cargo/config.toml of the repository. Git tracks that file. When you change the key, Cargo builds the crates that use it again.

Prepare the website

Install Node.js 22.12.0 or later. Use the pnpm version specified by packageManager in web/package.json. Run pnpm commands from web/.

cd web
pnpm install --frozen-lockfile
pnpm dev

Open the local URL printed by Astro. Use /docs/ for Chinese documentation. Use /en/docs/ for English documentation.

Select checks

Run these recipes from the repository root:

Change	During work	Before handoff
Rust code	just test-pkg <crate> [filter]	just check
A fork in forks/	just forks	just check and just forks
Documentation or harness	just plans after plan changes	just docs
Website or published documentation	just web	just web; also just docs for plan changes

just check runs build, tests, Clippy, and formatting checks in that order. just forks runs the tests of the forks the launcher builds from. CI runs just ci, which is just check and then just forks. just web runs dependency installation, Astro checks, website tests, and the site build. Do not report a check as passed until it finishes successfully.