[Rust 공식문서 한국어 정리] ㉛. Rust 기능 플래그(Feature Flags) 가이드

[Rust 공식문서 한국어 정리] ㉛. Rust 기능 플래그(Feature Flags) 가이드

원문 제목: The Features Section — Cargo Reference
작성자: Rust Cargo Team

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

이 문서는 Cargo의 기능 플래그(Feature Flags) 시스템을 사용해 선택적 기능을 관리하는 방법을 설명합니다.
크레이트의 컴파일 시간과 의존성 크기를 줄이면서도 다양한 사용 사례를 지원하는 유연한 구성 방법을 다룹니다.
기능의 선언, 활성화, 의존성 연결, 그리고 상호 배타적인 기능 그룹 설정까지 체계적으로 안내합니다.
no_std 환경, 임베디드, WASM 등 제한된 환경에서 불필요한 기능을 제외하는 전략도 포함합니다.
라이브러리와 애플리케이션 모두에서 필수적인 구성 관리 개념입니다.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔑 2. 핵심 개념 4가지
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

① Feature: Cargo.toml의 [features] 섹션에 선언된 선택적 기능 단위입니다.
② Default Feature: 별도 지정 없이 활성화되는 기본 기능 모음입니다.
③ Optional Dependency: 기능과 연결된 선택적 의존성으로, 해당 기능이 활성화될 때만 컴파일됩니다.
④ Feature Unification: 워크스페이스 내에서 동일한 크레이트의 기능이 union(합집합)으로 처리됩니다.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📖 3. 주요 내용 상세
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

기능은 Cargo.toml의 [features] 섹션에서 이름과 활성화 조건을 정의합니다.
feature-name = ["dep:crate-name", "other-feature"] 형태로, 기능이 활성화될 때 함께 켜질 의존성이나 다른 기능을 지정할 수 있습니다.
기본 기능은 default = ["feature-a", "feature-b"]로 선언하며, 사용자가 default-features = false로 끌 수 있습니다.

선택적 의존성은 [dependencies]에서 optional = true로 표시합니다.
이 의존성은 Cargo.toml에 있더라도 해당 기능이 활성화되지 않으면 컴파일에 포함되지 않습니다.
의존성 이름 앞에 dep:를 붙여 기능 선언에서 명시적으로 참조하는 것이 권장됩니다.

기능 활성화는 의존성 지정 시 features = ["feature-name"]으로 합니다.
여러 기능을 조합할 수 있으며, 워크스페이스의 다른 멤버가 동일한 크레이트를 의존할 때 기능은 합집합으로 처리됩니다.
이를 Feature Unification이라 하며, 예상치 못한 컴파일 에러나 기능 누수(leak)의 원인이 될 수 있습니다.

상호 배타적인 기능은 cfg를 활용해 런타임 검증합니다.
Cargo 자체는 상호 배타적 기능을 직접 금지하지 않으므로, 컴파일 타임 assert(cfg)나 런타임 패닉으로 충돌을 방지해야 합니다.
또한 weak dependency features를 사용하면 선택적 의존성의 기능만 선택적으로 활성화할 수 있습니다.

no_std 환경에서는 std 기능을 선택적으로 제공하는 것이 일반적입니다.
#[cfg(feature = "std")]로 std 전용 코드를 분리하고, 기본 기능에서 제외하면 임베디드나 WASM에서도 사용 가능합니다.
alloc 기능을 별도로 두어 힙 할당은 가능하지만 std는 필요 없는 환경도 지원할 수 있습니다.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🛠 4. 실전 활용
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

라이브러리의 컴파일 시간을 줄이기 위해 heavy 기능(JSON 파싱, 비동기 런타임 등)을 선택적 기능으로 분리합니다.
임베디드 타겟에서는 default-features = false로 std 관련 기능을 끄고 no_std로 빌드합니다.
cargo hack --feature-powerset으로 모든 기능 조합을 테스트하여 기능 간 상호작용을 검증합니다.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ 5. 정리
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

기능 플래그는 Rust 크레이트의 유연성과 효율성을 동시에 확보하는 핵심 메커니즘입니다.
기본 기능, 선택적 의존성, 기능 통합의 개념을 정확히 이해하면 의도치 않은 빌드 문제를 방지할 수 있습니다.
no_std 지원과 컴파일 시간 최적화를 위해서는 기능 설계가 매우 중요합니다.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔗 출처 링크
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

원문: https://doc.rust-lang.org/cargo/reference/features.html
Cargo Features Guide: https://doc.rust-lang.org/cargo/reference/features-examples.html

#Rust #FeatureFlags #Cargo #Configuration #no_std #Build #번역