Rust 설치와 Cargo 첫 프로젝트: rustup부터 Clippy까지

Rust를 처음 설치했다면 rustc --version만 확인하고 끝내기 쉽습니다. 하지만 실제 프로젝트에 필요한 시작점은 조금 더 넓습니다. rustup으로 도구 체인을 관리하고 Cargo로 크레이트를 만든 뒤 포맷·린트·테스트까지 한 번에 통과해야 개발 환경이 제대로 준비됐다고 볼 수 있습니다.

이 글에서는 빈 디렉터리에서 작은 실행 프로그램을 만들고 cargo fmt --check, cargo clippy -- -D warnings, cargo test까지 실행합니다. 명령은 Linux stable Rust 1.98.1을 기준으로 합니다. rustup 설치 프로그램 실행, Windows 설치, rustup component add, rustup update stable은 각 플랫폼의 설치 절차를 따릅니다.

1. rustup, rustc, Cargo의 역할

도구 이름이 비슷해 처음에는 헷갈립니다. 역할은 다음처럼 나누면 됩니다.

rustup: stable·beta·nightly 같은 Rust 도구 체인과 추가 컴포넌트를 설치하고 전환합니다.
rustc: Rust 소스 코드를 컴파일합니다.
cargo: 프로젝트 생성, 의존성 관리, 빌드, 실행, 테스트를 맡습니다.
rustfmt: 정해진 스타일로 Rust 코드를 포맷합니다.
clippy: 컴파일은 되지만 더 안전하거나 명료하게 쓸 수 있는 코드를 린트로 찾습니다.

rustup은 Rust 버전과 관련 도구를 관리하는 명령줄 도구입니다. 공식 설치 프로그램을 쓰면 Cargo도 함께 설치됩니다. rustfmt와 Clippy는 rustup 컴포넌트이므로 빠졌다면 나중에 추가할 수 있습니다.

2. Linux와 macOS에서 설치하기

rustup 설치 페이지는 셸 스크립트를 내려받아 실행하는 명령을 제공합니다. 한 줄짜리 파이프 명령은 편하지만 여기서는 파일을 먼저 저장하고 내용을 확인한 뒤 실행합니다.

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs -o rustup-init.sh
less rustup-init.sh
sh rustup-init.sh

설치 프로그램에서 특별한 이유가 없다면 stable 기본 도구 체인을 선택하면 됩니다. 셸을 다시 열었는데 cargo를 찾지 못한다면 Cargo 환경 파일을 현재 셸에 불러옵니다.

. "$HOME/.cargo/env"

Rust 컴파일에는 링커가 필요합니다. Linux에서 링크 오류가 난다면 배포판의 C 빌드 도구를 설치해야 합니다. 예를 들어 Debian·Ubuntu 계열은 build-essential, Fedora 계열은 C 개발 도구 그룹을 사용합니다. macOS에서는 보통 Xcode Command Line Tools가 이 역할을 맡습니다. 패키지 이름은 운영체제 버전에 따라 달라질 수 있으므로 해당 배포판 문서를 확인하는 편이 안전합니다.

3. Windows에서 설치하기

Windows에서는 Rust 도구 설치 페이지에서 rustup-init.exe를 내려받아 실행합니다. MSVC 도구 체인을 쓸 때는 Visual Studio Build Tools와 Windows SDK가 필요할 수 있습니다. 설치 프로그램이 Visual Studio 구성 요소 설치를 요청하면 C++ 빌드 도구를 포함해야 링커 오류를 피할 수 있습니다.

PowerShell이나 Windows Terminal을 새로 연 다음 아래 검증 명령을 실행합니다. WSL 안에서 개발한다면 Windows용 실행 파일과 섞지 말고 WSL의 Linux 셸에서 Linux 절차를 사용합니다.

4. 도구 체인 확인

버전 번호만 보는 것보다 활성 도구 체인과 컴포넌트까지 같이 확인하는 편이 낫습니다.

rustc --version
cargo --version
rustup show active-toolchain
rustup component list --installed

예제의 기준 버전은 다음과 같습니다.

rustc 1.98.1 (48a229cea 2026-09-01)
cargo 1.98.1 (797e8a9bc 2026-08-05)
rustfmt 1.9.0-stable (48a229ceae 2026-09-01)
clippy 0.1.98 (48a229ceae 2026-09-01)

rustfmt나 Clippy가 목록에 없다면 추가합니다.

rustup component add rustfmt clippy

도구 체인 업데이트는 간단합니다.

rustup update stable

다만 팀 프로젝트에서는 무조건 최신 버전으로 올리기보다 저장소가 지정한 도구 체인을 우선해야 합니다. 루트의 rust-toolchain.toml에 채널과 컴포넌트를 적어 두면 해당 디렉터리에서 Cargo를 실행할 때 rustup이 설정을 따릅니다.

[toolchain]
channel = "stable"
profile = "minimal"
components = ["rustfmt", "clippy"]

minimal 프로필은 컴파일에 필요한 핵심 구성만 설치하고 포맷터와 린터는 components에서 명시합니다. 프로젝트가 정확한 컴파일러 버전에 의존한다면 stable 대신 필요한 버전을 고정할 수 있습니다. 반대로 학습용 저장소라면 stable을 따라가며 주기적으로 테스트하는 선택도 합리적입니다.

5. 첫 Cargo 크레이트

Cargo에서 패키지는 하나 이상의 크레이트를 담습니다. 지금 만들 프로젝트는 실행 가능한 binary crate 하나로 구성됩니다. 기존 Git 저장소 안에서도 예제가 독립적으로 동작하도록 --vcs none을 붙였습니다.

cargo new endpoint-check --bin --vcs none
cd endpoint-check

cargo new는 Cargo.toml과 src/main.rs를 만듭니다. Cargo.toml에는 패키지 이름, 버전, Rust edition과 의존성이 들어갑니다. 현재 stable Cargo가 만든 기본 파일은 다음과 같은 형태입니다.

[package]
name = "endpoint-check"
version = "0.1.0"
edition = "2024"

[dependencies]

src/main.rs를 아래 코드로 바꿉니다. 실행 결과를 만드는 작은 함수와 단위 테스트를 같은 파일에 두었습니다. 이후 글에서 확장할 엔드포인트 도구의 가장 작은 출발점입니다.

fn status_line(name: &str, url: &str) -> String {
    format!("{name}: {url}")
}

fn main() {
    println!("{}", status_line("docs", "https://doc.rust-lang.org"));
}

#[cfg(test)]
mod tests {
    use super::status_line;

    #[test]
    fn formats_an_endpoint() {
        assert_eq!(
            status_line("docs", "https://doc.rust-lang.org"),
            "docs: https://doc.rust-lang.org"
        );
    }
}

6. check, build, run의 역할

작성 중에는 먼저 cargo check를 돌리는 습관이 유용합니다. 이 명령은 최종 코드 생성을 생략하고 현재 패키지와 의존성의 오류를 검사합니다. 실행 파일이 필요하지 않은 짧은 피드백 루프에 맞습니다.

cargo check
cargo build
cargo run --quiet

cargo build는 기본적으로 개발용 실행 파일을 target/debug 아래에 만듭니다. cargo run은 필요하면 빌드한 뒤 프로그램을 실행합니다. --quiet은 Cargo 자체 메시지를 줄일 뿐 프로그램 출력은 남깁니다.

docs: https://doc.rust-lang.org

배포용 최적화 빌드는 cargo build --release입니다. 처음 배우는 단계에서 모든 실행을 release로 바꿀 필요는 없습니다. 컴파일 시간이 더 걸리고 빠른 수정·검증에는 기본 dev 프로필이 잘 맞습니다.

7. rustfmt 실행과 검사

Cargo 프로젝트 전체를 포맷할 때 cargo fmt 사용을 권합니다.

cargo fmt
cargo fmt --check

첫 명령은 파일을 수정합니다. 두 번째 명령은 포맷이 필요한 파일이 있으면 실패하므로 CI에 넣기 좋습니다. 로컬에서는 cargo fmt로 고치고 자동 검사에서는 cargo fmt --check로 변경 사항이 없는지 확인하는 구성이 단순합니다.

8. Clippy 경고를 오류로

Clippy의 일반적인 실행 방법은 다음과 같습니다.

cargo clippy

이 명령만으로도 기본 린트 그룹을 검사합니다. 이 글에서는 경고를 남긴 채 통과하지 않도록 한 단계 엄격하게 실행합니다.

cargo clippy -- -D warnings

-- 앞의 인자는 Cargo와 Clippy 서브커맨드가 처리하고 뒤의 -D warnings는 컴파일러 린트 설정으로 전달됩니다. 새 프로젝트나 학습용 예제에는 좋은 기준이지만 기존 코드베이스에 바로 적용하면 현재 경고 때문에 작업과 무관한 빌드가 깨질 수 있습니다. 그런 저장소에서는 린트 정책을 먼저 합의하고 점진적으로 켜는 편이 낫습니다.

Clippy가 제안을 했다고 전부 기계적으로 적용할 필요는 없습니다. 제안 이유를 읽고 코드 의도와 맞는지 확인해야 합니다. 자동 수정이 필요할 때도 커밋 전 diff와 테스트를 다시 봅니다.

9. 테스트 실행

#[test]가 붙은 함수는 Rust 테스트 하네스가 찾습니다. cargo test는 단위 테스트, 통합 테스트, 문서 테스트를 컴파일하고 실행합니다.

cargo test

테스트 출력의 핵심 구간은 다음과 같습니다.

running 1 test
test tests::formats_an_endpoint ... ok

첫 프로젝트의 완료 조건을 명령 하나로 묶으면 이 정도면 충분합니다.

cargo fmt --check
cargo clippy -- -D warnings
cargo test

세 명령이 모두 종료 코드 0을 반환하면 스타일, 기본 정적 분석, 현재 테스트를 통과한 상태입니다. 이것이 프로그램에 버그가 없다는 보증은 아닙니다. 아직 테스트하지 않은 동작과 환경 차이는 그대로 남습니다. 다만 컴파일만 되는 Hello, world!보다 훨씬 쓸 만한 출발선입니다.

10. 설치 문제 해결

cargo: command not found가 나오면 새 터미널을 열거나 $HOME/.cargo/bin이 PATH에 들어갔는지 확인합니다. Unix 셸에서는 . "$HOME/.cargo/env"로 현재 세션을 갱신할 수 있습니다.

링커를 찾지 못한다는 오류는 Rust 코드보다 시스템 빌드 도구 문제일 가능성이 큽니다. Linux의 C 컴파일러·링커 패키지나 Windows의 MSVC Build Tools를 먼저 확인합니다.

cargo fmt 또는 cargo clippy가 없다는 메시지는 해당 rustup 컴포넌트가 설치되지 않았다는 뜻일 수 있습니다. rustup component add rustfmt clippy를 실행한 뒤 다시 확인합니다. 특정 nightly 기능이 필요한 프로젝트가 아니라면 이 단계에서 nightly로 바꿀 이유는 없습니다.

11. 다음 단계

도구 체인이 준비됐으니 다음 글에서는 Rust의 불변 변수, 타입 추론, 명시적 타입, shadowing을 이 크레이트 안에서 다룹니다. 그 전에는 Cargo.toml, src/main.rs, target 디렉터리의 역할과 위 세 가지 검사 명령만 익혀 두면 됩니다.

전체 소스 코드

이 글의 전체 실행 가능한 소스는 GitHub의 Chapter 01 프로젝트에서 확인할 수 있습니다.

[Rust 실전 로드맵 01] Rust 설치와 Cargo 첫 프로젝트: rustup부터 Clippy까지