Building Phichain

Build Phichain from source with Rust and Cargo

Phichain is built with Rust and the Bevy game engine. This guide will walk you through setting up your development environment and building the project from source.

Prerequisites

Required Software

1. Install Rust

   Install Rust using rustup. The project uses stable Rust toolchain.

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   

   Verify installation:

   rustc --version
   cargo --version
   
2. Install platform-specific dependencies

   Phichain uses Bevy, which has platform-specific requirements.

   Linux

   Ubuntu/Debian:

   sudo apt-get update
   sudo apt-get install -y g++ pkg-config libx11-dev libasound2-dev libudev-dev
   sudo apt-get install -y libwayland-dev libxkbcommon-dev libxkbcommon-x11-0
   

   These packages provide:

   • Graphics support (X11, Wayland)
   • Audio support (ALSA)
   • Device management (udev)
   • Keyboard input handling

   Windows

   No additional dependencies required. The MSVC toolchain is recommended.

   Install Visual Studio Build Tools or Visual Studio with C++ support.

   macOS

   Xcode Command Line Tools are required:

   xcode-select --install
   

Clone the Repository

git clone https://github.com/ivan-1f/phichain.git
cd phichain

Building the Project

Phichain is a workspace project containing multiple crates. The main binary is phichain (the editor).

Development Build

Build with optimized dependencies but faster compile times:

cargo build

The workspace uses custom profile settings for faster development:

• Project code compiled with minimal optimization (opt-level = 1)
• Dependencies compiled with full optimization (opt-level = 3)

Release Build

Build all binaries with full optimizations:

Editor

cargo build -p phichain --release

Release builds use aggressive optimization:

• Link-Time Optimization (LTO) enabled
• Single codegen unit for maximum optimization
• All debug symbols stripped

Build Artifacts

Compiled binaries are located in:

• Debug builds: target/debug/
• Release builds: target/release/

Executables:

• phichain - Main chart editor application
• phichain-converter - Chart format conversion tool
• phichain-renderer - Chart rendering utility

Running Phichain

Development

cargo run -p phichain

On Windows, you can also use the convenience script:

start.bat

Running Tests

Run the full test suite:

cargo test

Test a specific crate:

cargo test -p phichain-chart

Code Quality Checks

The project enforces code quality through formatting and linting.

Format Check

cargo fmt --all -- --check

Auto-format code:

cargo fmt --all

Clippy Lints

Run Clippy with project settings:

cargo clippy --all-features --all-targets -- -D warnings

The project allows certain Clippy lints:

• type_complexity - Common in Bevy ECS systems
• too_many_arguments - Common in Bevy system parameters

Platform-Specific Builds

Build for specific targets:

Linux (x86_64)

cargo build --release --target x86_64-unknown-linux-gnu

You may need to install the target with rustup target add <target-triple> first.

Troubleshooting

Compilation is very slow

First-time builds can take 15-30 minutes due to Bevy and dependencies.

Tips to speed up compilation:

• Use cargo build (development) instead of --release during development
• Enable parallel compilation: cargo build -j $(nproc)
• Use a faster linker like mold (Linux) or lld
• Consider using cargo-chef for Docker builds

Linker errors on Linux

Ensure all system dependencies are installed:

sudo apt-get install -y g++ pkg-config libx11-dev libasound2-dev libudev-dev
sudo apt-get install -y libwayland-dev libxkbcommon-dev

Out of memory during compilation

Bevy projects can require significant RAM. Solutions:

• Reduce parallel jobs: cargo build -j 2
• Close other applications
• Add swap space
• Use a development build instead of release

Git dependency issues (bevy_prototype_lyon)

The project uses a git dependency for bevy_prototype_lyon (Bevy 0.16 compatibility).

If you encounter network issues:

# Clear cargo cache
rm -rf ~/.cargo/git
cargo clean
cargo build

Runtime errors or missing assets

Ensure you run the binary from the project root directory:

# From project root
./target/release/phichain

The application expects assets/ and lang/ directories to be present.

Build Configuration

The workspace is configured in Cargo.toml with optimized profile settings:

Cargo.toml

[profile.dev]
opt-level = 1  # Basic optimization for project code

[profile.dev.package."*"]
opt-level = 3  # Full optimization for dependencies

[profile.release]
lto = true           # Link-time optimization
opt-level = 3        # Maximum optimization
codegen-units = 1    # Single codegen unit
incremental = false  # Disable incremental compilation
debug = false        # Strip debug symbols

Release builds take significantly longer but produce much faster binaries. Use development builds for iteration.

Next Steps

Architecture

Learn about Phichain’s crate structure and design

Contributing

Start contributing to the project