설치와 도구
설치와 첫 프로그램
이 장에서는 설치와 첫 프로젝트 생성에 필요한 명령 절차를 다룹니다. 커널 패턴을 읽기 전에 이 절차를 먼저 실행하십시오.
호스트 요구 사항
배포된 바이너리에는 GLIBC_2.34가 필요하지만 20.04에는 2.31이 포함되어 있으므로, 호스트는 Ubuntu 22.04 이상의 x86_64-unknown-linux-gnu여야 합니다. macOS나 arm64에서는 모든 작업을 linux/amd64 컨테이너 안에서 실행하십시오.
sudo apt install build-essential libclang-dev # every build
sudo apt install gcc-aarch64-linux-gnu # only for the NPU build (cargo furiosa-opt)
아래 툴체인은 다음 항목을 포함하지 않으므로 툴체인보다 먼저 설치하십시오. rustc는 시스템의 cc로 호스트 바이너리를 링크하고, furiosa-opt-std의 빌드 스크립트는 libclang.so를 로드합니다.
스타터 설치와 실행
Furiosa 옵티마이저는 rustc 드라이버이며, 고정된 nightly 버전에 ABI가 묶여 있습니다. 툴체인과 호스트 도구를 설치하고 표준 스타터를 생성한 다음, CPU에서 실행하고 커널을 컴파일하십시오.
rustup toolchain install nightly-2026-05-01
cargo +nightly-2026-05-01 install cargo-binstall
cargo +nightly-2026-05-01 binstall cargo-furiosa-opt
cargo install cargo-generate
cargo generate furiosa-ai/furiosa-opt base-template
cd base-template
cargo run --release --bin gemm
cargo furiosa-opt compile
생성된 프로젝트에서는 rust-toolchain.toml이 같은 채널을 고정합니다. Cargo는 해당 디렉터리에서 이 채널을 자동으로 활성화합니다.
일반 cargo 호출은 CPU에서 빌드하고 실행합니다. cargo furiosa-opt는 NPU용으로 빌드하고 커널을 미리 컴파일합니다.
NPU 요구 사항
NPU 빌드에는 Furiosa SDK와 물리 NPU도 필요합니다. NPU 빌드는 SDK 커널 드라이버와 PE 런타임(furiosa-driver-rngd, furiosa-smi 및 관련 구성 요소)을 통해 디스패치됩니다. SDK 문서를 참조하십시오.
CPU 빌드에는 SDK가 필요하지 않습니다. CPU 빌드는 NPU 의존성 없이 호스트 측에서 실행됩니다.
생성된 프로젝트
이 명령 절차는 base-template 스타터의 뼈대를 생성합니다. 이 템플릿은 실행 가능한 표준 예제이며, 지속적 통합(CI)은 현재 소스를 임의의 이름으로 생성한 뒤 CPU에서 테스트합니다. 생성된 템플릿을 수정하기 전에 텐서와 축약과 커널 검증을 읽으십시오. 에이전트가 변경 사항을 구현할 때는 커널 작성 스킬(Kernel Authoring Skill)을 사용하십시오.
템플릿 레이아웃
생성된 Cargo.toml은 [package.metadata.furiosa-opt]를 선언하며, 이 선언은 해당 패키지를 커널 컴파일 대상으로 지정합니다. src/kernel/에는 각 #[device] 함수가 들어 있고, src/kernel/mod.rs는 이 커널 모듈들을 다시 내보냅니다. src/*.rs에 바로 위치한 파일은 launch(kernel, ...)를 호출하는 호스트 바이너리이며, 각자의 호스트 오라클 테스트를 포함합니다. 각 호스트 바이너리에는 Cargo.toml에 path = "src/<name>.rs"를 지정한 명시적인 [[bin]] 항목이 있습니다. 컴파일러 플러그인은 src/를 루트로 하는 cargo 타깃을 스캔하므로, 호스트 바이너리를 src/bin/, examples/, tests/로 옮기지 마십시오.
base-template/
├── Cargo.toml
├── rust-toolchain.toml
└── src/
├── lib.rs
├── kernel/
│ ├── mod.rs
│ └── <name>_kernel.rs
└── <name>.rs
커널 추가
#[device(...)] pub fn <name>_kernel(...)함수를 담은src/kernel/<name>_kernel.rs를 추가하십시오.src/kernel/mod.rs에서 이를 다시 내보내십시오.- 호스트 프로그램, 호스트 오라클,
launch(<name>_kernel, ...)호출을 담은src/<name>.rs를 추가하십시오. - 호스트 프로그램을
Cargo.toml에[[bin]]타깃으로 등록하십시오. - Kernel Optimizer 명령 레퍼런스를 참고하여 커널을 실행하십시오.
개발 도구
Furiosa IR Optimizer는 Furiosa SDK 컴파일러를 보완합니다. 프로그래머가 vISA를 직접 작성하거나 다른 컴파일러로 생성할 때 세밀하게 제어할 수 있게 해 줍니다.
Kernel Optimizer
CLI 문법과 컴파일 동작은 Kernel Optimizer 도구 레퍼런스에서 다룹니다.
언어 서버
furiosa-rust-analyzer-proxy는 표준 Rust IDE 기능을 제공하며, Furiosa 매핑 표현식을 읽기 쉬운 형태로 보여 줍니다. Stride<Symbol<A>, 8>처럼 장황한 매핑 타입을 m![A / 8]로 표시합니다. 설치와 설정 방법은 언어 서버 도구 레퍼런스를 참고하십시오.
Schedule Viewer
Schedule Viewer는 실행 타임라인을 시각화하여 성능 병목 지점을 찾는 데 도움을 줍니다. furiosa-opt로 스케줄 JSON 파일을 내보낸 다음 furiosa-schedule-viewer로 여십시오.
설치와 사용 방법은 Schedule Viewer 도구 레퍼런스를 참고하십시오.