D - 유용한 개발 도구

러스트를 쓰다 보면 문법만큼 도구를 다루는 능력이 중요해집니다. rustfmt, cargo fix, Clippy, rust-analyzer 같은 도구는 되풀이되는 실수를 줄이고 코드의 품질을 고르게 유지해 줍니다. 아래 표는 개발 중에 만나는 문제마다 먼저 쓸 도구와, 그 도구가 무엇을 바꾸는지 정리한 것입니다.

코드를 쓰며 탐색하고 곧바로 진단을 받을 때는 rust-analyzer를 씁니다. 기본 분석은 읽기만 하지만, 고른 코드 액션(code action)은 소스를 바꿀 수 있고, 실제 컴파일과 테스트의 통과를 대신하지는 않습니다. 타입이나 대여, 컴파일 오류는 cargo check로 확인하며, 소스는 그대로 두고 target/에 메타데이터와 캐시만 만듭니다. 기본으로 패키지의 라이브러리와 바이너리, 의존성을 검사하고, 테스트까지 보려면 --all-targets를 줍니다. cargo fmt는 기본으로 소스를 고치고, cargo fmt --all -- --check는 작업공간 전체의 차이만 보고합니다. cargo fix는 자동으로 적용해도 되는 컴파일러의 제안으로 소스를 바꾸며, 활성화한 기능(feature)과 지금 플랫폼의 cfg에 들어간 코드만 다룹니다. cargo clippy는 기본으로 진단만 하고 --fix를 주면 일부 소스를 바꾸며, -A, -W, -D로 프로젝트의 린트 정책을 정합니다. cargo test는 유닛 테스트, 통합 테스트, 라이브러리의 문서 테스트를 실행하고, cargo doc --no-deps는 target/doc/에 API 문서를 만들 뿐 문서 테스트는 실행하지 않습니다. 소스를 바꾸는 명령은 되돌릴 수 있는 깨끗한 작업 트리에서 실행합니다.

부록 D - 유용한 개발 도구

이 부록에서는 러스트 프로젝트가 제공하는 유용한 개발 도구 몇 가지를 이야기합니다. 자동 포맷팅, 경고를 빠르게 고치는 방법, 린터, IDE와의 연동을 봅니다.

rustfmt로 자동 포맷팅하기

rustfmt 도구는 커뮤니티의 코드 스타일에 맞춰 코드를 다시 포맷팅합니다. 많은 공동 프로젝트가 rustfmt를 써서, 러스트를 쓸 때 어떤 스타일을 쓸지에 관한 논쟁을 막습니다. 모두가 이 도구로 코드를 포맷팅하기 때문입니다.

러스트 설치에는 기본으로 rustfmt가 들어 있으므로, 시스템에 이미 rustfmt와 cargo-fmt 프로그램이 있을 것입니다. 이 두 명령은 rustc와 cargo의 관계와 비슷합니다. rustfmt는 더 세밀하게 다룰 수 있고, cargo-fmt는 Cargo를 쓰는 프로젝트의 관례를 이해합니다. Cargo 프로젝트를 포맷팅하려면 다음을 입력합니다.

cargo fmt

이 명령을 실행하면 현재 크레이트의 모든 러스트 코드가 다시 포맷팅됩니다. 이 명령은 코드의 의미가 아니라 스타일만 바꿉니다. 파일을 바꾸지 않고 차이만 확인하려면 cargo fmt --all -- --check를 쓰며, CI에서 흔히 이렇게 확인합니다. rustfmt에 대한 자세한 정보는 rustfmt 문서를 보세요.

cargo fix로 컴파일러 제안 적용하기

rustfix 도구는 러스트 설치에 들어 있으며, 문제를 고치는 분명한 방법이 있는 컴파일러 경고를 자동으로 고칠 수 있습니다. 이런 경고는 아마 본 적이 있을 것입니다. 예를 들어 다음 코드를 봅니다.

fn main() {
    let mut x = 42;
    println!("{x}");
}

여기서는 변수 x를 가변으로 정의했지만, 실제로 바꾸지는 않습니다. 러스트는 이것에 대해 경고합니다.

cargo build

   Compiling myprogram v0.1.0 (file:///projects/myprogram)
warning: variable does not need to be mutable
 --> src/main.rs:2:9
  |
2 |     let mut x = 42;
  |         ----^
  |         |
  |         help: remove this `mut`
  |
  = note: `#[warn(unused_mut)]` (part of `#[warn(unused)]`) on by default

경고는 mut 키워드를 지우라고 제안합니다. cargo fix 명령을 실행하면 rustfix 도구로 이 제안을 자동으로 적용할 수 있습니다.

cargo fix

    Checking myprogram v0.1.0 (file:///projects/myprogram)
      Fixing src/main.rs (1 fix)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.59s

src/main.rs를 다시 보면, cargo fix가 코드를 바꿨다는 것을 볼 수 있습니다. 출력의 Fixing src/main.rs (1 fix) 줄이 이 변경을 알린 것이며, 바뀐 곳은 let mut x의 mut 하나뿐입니다.

fn main() {
    let x = 42;
    println!("{x}");
}

이제 변수 x는 불변이고, 경고는 더 이상 나오지 않습니다.

cargo fix는 안에서 cargo check를 실행해, rustc가 자동으로 적용해도 된다고 분류한 제안만 소스에 반영합니다. 모든 경고를 고치는 명령은 아니며, 활성화한 기능과 지금 대상의 cfg에 들어가 실제로 검사된 코드만 다룹니다. 기본으로 버전 관리 시스템이 있는지, 작업 트리에 저장하지 않은 변경이 없는지 확인하므로, 먼저 변경을 커밋하거나 따로 보관해 되돌릴 지점을 만듭니다. --allow-no-vcs, --allow-dirty, --allow-staged는 이 확인을 건너뛰므로, 변경을 잃지 않을 까닭과 복구할 방법이 있을 때만 씁니다. 자동으로 고친 뒤에는 바뀐 내용을 읽고 cargo test를 실행합니다.

cargo fix 명령으로 서로 다른 러스트 에디션 사이에서 코드를 옮길 수도 있습니다. 이 명령은 Cargo.toml의 edition 값을 바꾸지 않으므로, 코드의 변경을 확인한 뒤 매니페스트를 직접 바꾸고 테스트해야 합니다. 에디션은 E - 에디션에서 다룹니다.

Clippy로 더 많은 린트 사용하기

Clippy 도구는 흔한 실수를 잡아 러스트 코드를 개선할 수 있도록 코드를 분석하는 린트(lint)의 모음입니다. Clippy는 러스트의 표준 설치에 들어 있습니다. Cargo 프로젝트에서 Clippy의 린트를 실행하려면 다음을 입력합니다.

cargo clippy

예를 들어 다음 프로그램처럼, 수학 상수 파이(pi)의 근삿값을 쓰는 프로그램을 쓴다고 합시다. 이 코드는 컴파일러의 검사를 통과하고 실행도 되지만, Clippy에는 손으로 적은 이런 근삿값을 찾아내는 검사가 따로 있습니다.

fn main() {
    let x = 3.1415;
    let r = 8.0;
    println!("the area of the circle is {}", x * r * r);
}

이 프로젝트에서 cargo clippy를 실행하면 다음 오류가 납니다. note 줄의 deny는 이 검사가 기본으로 경고가 아니라 오류 수준이라는 뜻이어서, 출력이 warning이 아니라 error로 시작합니다.

error: approximate value of `f{32, 64}::consts::PI` found
 --> src/main.rs:2:13
  |
2 |     let x = 3.1415;
  |             ^^^^^^
  |
  = help: consider using the constant directly
  = help: for further information visit https://rust-lang.github.io/rust-clippy/rust-1.99.0/index.html#approx_constant
  = note: `#[deny(clippy::approx_constant)]` on by default

이 오류는 러스트에 이미 더 정확한 PI 상수가 정의되어 있으며, 그 상수를 쓰면 프로그램이 더 정확해진다고 알려 줍니다. 그러면 PI 상수를 쓰도록 코드를 바꿉니다. 다음 코드는 Clippy에서 아무 오류나 경고도 나지 않습니다.

fn main() {
    let x = std::f64::consts::PI;
    let r = 8.0;
    println!("the area of the circle is {}", x * r * r);
}

Clippy의 기본 린트 묶음은 clippy::all이며, cargo clippy -- -D warnings처럼 경고를 실패로 다루거나, 코드나 Cargo.toml의 [lints] 섹션에서 특정 린트를 allow, warn, deny로 정해 프로젝트의 정책을 만들 수 있습니다. cargo clippy --fix는 일부 제안을 자동으로 적용하며, cargo fix처럼 되돌릴 수 있는 작업 트리에서 실행합니다. Clippy에 대한 자세한 정보는 Clippy 문서를 보세요.

rust-analyzer를 사용한 IDE 통합

러스트 커뮤니티는 IDE와의 연동을 돕기 위해 rust-analyzer를 권합니다. 이 도구는 언어 서버 프로토콜(Language Server Protocol)로 통신하는, 컴파일러를 중심으로 한 유틸리티의 모음입니다. 언어 서버 프로토콜은 IDE와 프로그래밍 언어가 서로 통신하기 위한 명세입니다. 서로 다른 여러 클라이언트에서 rust-analyzer를 쓸 수 있으며, 예를 들어 Visual Studio Code의 Rust analyzer 확장이 있습니다.

설치 방법은 rust-analyzer 프로젝트의 홈페이지를 보고, 사용하는 IDE에 언어 서버 지원을 설치하세요. 편집기의 확장이 서버를 직접 관리하지 않는 환경이라면, rustup으로 지금의 툴체인에 맞는 구성 요소를 더할 수 있습니다.

rustup component add rust-analyzer

그러면 IDE에서 자동 완성, 정의로 이동, 인라인 오류 같은 기능을 쓸 수 있게 됩니다.

API 문서와 문서 테스트 구분하기

cargo doc은 rustdoc으로 로컬 패키지와, 기본으로 그 의존성의 API 문서를 target/doc에 만듭니다. 의존성의 문서를 빼고 곧바로 열려면 다음처럼 실행합니다.

cargo doc --no-deps --open

이 명령은 문서를 그릴 뿐 문서 속 예제를 테스트하지 않습니다. 라이브러리의 문서화 주석에 있는 코드 예제를 컴파일하고 실행하려면, 기본 cargo test를 쓰거나 문서 테스트만 따로 실행합니다.

cargo test --doc

문서 테스트는 rustdoc이 코드 블록을 뽑아 테스트 실행 파일로 만드는 것이며, 일반 cargo test에도 기본으로 들어 있습니다. 이 도구들은 한 번 실행하고 끝내는 목록보다, 편집으로 돌아오는 반복 과정으로 묶을 때 쓸모가 큽니다. 아래 그림이 그 과정입니다.

rust-analyzer로 타입 정보와 정의 이동, 인라인 진단을 보며 작은 변경 하나를 만들고, cargo check로 최종 코드를 만들기 전에 타입과 대여, 컴파일 오류를 빠르게 확인합니다. cargo fmt --all -- --check로 파일을 바꾸지 않고 포맷 차이를 검사하고, cargo clippy -- -D warnings로 프로젝트가 고른 린트 정책을 실패 조건으로 확인합니다. cargo test로 유닛 테스트, 통합 테스트, 문서 테스트를 실행해 동작과 예제를 검증하고, cargo doc --no-deps로 그린 공개 API를 읽어 발견한 문제를 다시 첫 단계의 편집으로 되돌립니다. fmt, fix, clippy --fix 같은 자동 수정은 이 읽기만 하는 과정에서 실패의 원인을 이해한 뒤, 되돌릴 수 있는 작업 트리에서 따로 실행합니다. 실패를 한꺼번에 덮지 말고 작은 변경으로 고친 뒤 같은 명령을 다시 실행해야, 원인과 결과를 이어서 볼 수 있습니다.

정리

• cargo fmt는 코드의 의미는 그대로 두고 커뮤니티 스타일로 포맷팅하며, cargo fmt --all -- --check는 차이만 검사합니다.
• cargo fix는 컴파일러가 자동으로 적용해도 된다고 한 제안만 소스에 반영하고, 버전 관리와 깨끗한 작업 트리를 기본으로 확인합니다. 에디션을 옮길 때도 씁니다.
• cargo clippy는 흔한 실수를 잡는 린트를 실행하며, -D warnings나 [lints] 설정으로 프로젝트의 정책을 정할 수 있습니다.
• rust-analyzer는 언어 서버 프로토콜로 IDE에 자동 완성, 정의로 이동, 인라인 오류를 제공하지만, 컴파일과 테스트를 대신하지는 않습니다.
• cargo doc은 API 문서를 만들 뿐이고, 문서 속 예제는 cargo test나 cargo test --doc이 실행합니다.

연습 문제

1. 어떤 도구를 먼저 쓸까

(가) PR의 코드 스타일이 팀과 다른지 CI에서 확인하고 싶다. (나) 경고 수십 개 가운데 컴파일러가 고치는 방법을 아는 것만 한 번에 고치고 싶다. (다) 문서 주석의 예제가 지금의 API로 여전히 동작하는지 확인하고 싶다. 각각 어떤 명령을 쓰나요?

2. 경고를 실패로 만들기

팀이 Clippy의 경고가 하나라도 있으면 CI가 실패하기를 원하지만, clippy::too_many_arguments만은 허용하기로 했습니다. 어떻게 설정하나요?

다음 부록 E - 에디션에서는 러스트 에디션이 무엇이고 크레이트를 다른 에디션으로 옮기는 방법을 살펴봅니다.