[Rust 공식문서 한국어 정리] 56. Rust MSRV 가이드

[Rust 공식문서 한국어 정리] 56. Rust MSRV 가이드



원문 제목: The rust-version field — Cargo Reference

작성자: Rust Cargo Team



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📌 1. 서론 — 이 문서가 다루는 내용

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━



이 문서는 Rust 프로젝트의 MSRV(Minimum Supported Rust Version)를 정의하고 관리하는 방법을 설명합니다.

Cargo.toml의 rust-version 필드, MSRV 선택 전략, 그리고 CI에서의 MSRV 검증 방법을 다룹니다.

라이브러리와 애플리케이션이 각각 어떤 기준으로 MSRV를 설정하고, 사용자에게 어떤 영향을 미치는지를 중심으로 설명합니다.

생태계의 다양한 사용자 환경을 고려하여, 호환성과 최신 기능 사이의 균형을 맞추는 방법을 제시합니다.

오픈소스 라이브러리를 배포하거나 팀 내 Rust 버전을 관리하는 개발자에게 필수적인 내용입니다.



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔑 2. 핵심 개념 4가지

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━



① MSRV: 프로젝트가 컴파일되고 동작하는 데 필요한 최소 Rust 컴파일러 버전입니다.

② rust-version: Cargo.toml에 명시하는 필드로, Cargo가 이 버전 미만에서는 컴파일을 거부합니다.

③ Edition: MSRV와는 별개이지만, 에디션 변경은 종종 MSRV 상승의 주요 원인이 됩니다.

④ MSRV Policy: 프로젝트가 MSRV를 얼마나 자주 올리고, 어떤 기준으로 결정하는지에 대한 정책입니다.



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📖 3. 주요 내용 상세

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━



MSRV는 Cargo.toml의 [package] 섹션에 rust-version = "1.60" 형태로 명시합니다.

이 필드는 Cargo 1.56부터 도입되었으며, 이전에는 package.metadata.msrv 등의 비공식 방식을 사용했습니다.

명시된 MSRV보다 낮은 버전의 컴파일러로 빌드를 시도하면, Cargo는 에러 메시지를 출력하고 종료합니다.



라이브러리의 MSRV는 사용자의 컴파일러 버전 분포를 고려하여 설정해야 합니다.

Debian stable, Enterprise Linux 등의 배포판에 포함된 Rust 버전이 중요한 기준이 됩니다.

너무 최신 버전을 MSRV로 설정하면, 이러한 환경의 사용자가 라이브러리를 사용할 수 없게 됩니다.



MSRV를 올리는 시점은 주요 기능 추가나 의존성 업데이트에 맞추는 것이 일반적입니다.

새로운 언어 기능(let else, GAT stabilization 등)이 필요해지면, 해당 기능이 안정화된 버전을 MSRV로 설정합니다.

보안 패치나 중요한 버그 수정은 MSRV를 유지하면서도 backport가 가능한 경우가 많습니다.



CI에서 MSRV를 검증하려면, rustup으로 특정 버전을 설치하고 cargo check --all-targets를 실행합니다.

cargo-msrv라는 도구는 이진 탐색으로 프로젝트의 실제 최소 지원 버전을 자동으로 찾아줍니다.

GitHub Actions의 matrix에서 stable, beta, nightly, MSRV를 모두 테스트하는 것이 권장됩니다.



cargo-hack의 --rust-version 플래그는 의존성의 MSRV도 함께 고려하여 빌드를 시뮬레이션합니다.

이를 통해 자신의 MSRV가 의존성의 MSRV보다 낮아서 발생하는 빌드 실패를 사전에 감지할 수 있습니다.



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🛠 4. 실전 활용

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━



라이브러리의 README와 CHANGELOG에 MSRV 정책과 현재 MSRV를 명시합니다.

CI matrix에 MSRV job을 추가하여, 모든 PR이 MSRV에서 컴파일되는지 검증합니다.

Major 버전 업데이트 시에만 MSRV를 올리고, Minor/Patch에서는 최대한 유지하여 사용자 부담을 줄입니다.



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ 5. 정리

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━



MSRV는 프로젝트의 호환성 약속이며, 사용자와의 신뢰 계약입니다.

Cargo.toml의 rust-version으로 명시하고, CI에서 지속적으로 검증해야 합니다.

생태계의 다양한 환경을 배려하여, 무분별한 MSRV 상승을 피하세요.



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔗 출처 링크

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━



원문: https://doc.rust-lang.org/cargo/reference/manifest.html#the-rust-version-field

cargo-msrv: https://github.com/foresterre/cargo-msrv



#Rust #MSRV #Compatibility #Cargo #VersionManagement #OpenSource #번역