러스트 카고와 crates.io

카고 공식 문서

https://doc.rust-lang.org/stable/cargo/

Introduction - The Cargo Book

 

 

 

 

릴리스 프로필

설정값을 가지고 있는 미리 정의된 커스터마이징 가능한 프로필

이 설정값으로 프로그래머는 코드 컴파일을 위한 다양한 옵션을 제어할 수 있음

각 프로필은 다른 프로필과 독립적으로 설정됨

프로필은 Cargo.toml 파일에 [profile.*] 섹션을 명시적으로 추가하여 설정 가능 (없으면 기본값)

 

 

카고의 주요 프로필

- dev 프로필 (cargo build)

개발에 적합한 기본값으로 정의되어 있음

 

- release 프로필 (cargo build --release)

릴리스 빌드용 설정을 기본 값으로 가짐

 

 

카고 프로필 섹션 추가

[profile.dev]
opt-level = 0

[profile.release]
opt-level = 3

opt-level은 러스트가 코드에 적용할 최적화 수치이고 0~3의 값을 가짐

높은 최적화 수치를 적용할수록 컴파일 시간이 늘어남

dev 프로필의 기본값은 0, release 프로필의 기본값은 3

 

 

 

 

 

유용한 문서화 주석 만들기

crates.io 러스트의 공식 패키지 레지스트리로 개발자들이 자신의 패키지를 배포하여 다른 사람들과 코드를 공유할 수 있음

/// Add one to the number given
///
/// # Examples
/// ```
/// let arg = 5;
/// let answer = my_crate::add_one(arg);
/// 
/// assert_eq!(6, answer);
/// ```
pub fn add_one(x: i32) {
    x + 1
}

 

문서화 주석은 슬래시 3개로 표현 ///

cargo doc 명령을 실행하면 이 문서화 주석으로 부터 HTML 문서를 생성할 수 있음

이 명령어는 러스트와 함께 배포되는 rustdoc 도구를 실행하여 생성된 HTML 문서를 target/doc 디렉터리에 넣음

cargo doc --open을 실행하면 현재 크레이트 문서에 대해 (크레이트가 가진 모든 디펜던시의 문서까지) HTML을 생성하고 

그 결과를 웹 브라우저에 띄워줌

 

 

러스트 문서에 자주 사용되는 절

위 예시에서 # Exampls 절을 만들었는데, 이외에 크레이트 저자가 문서에서 자주 사용하는 절은 아래와 같음

 

- Panics

: 문서화된 함수가 패닉을 일으킬 수 있는 시나리오

 

- Errors

: 해당 함수가 Result를 반환하는 경우에 발생할 수 있는 에러의 종류와 해당 에러가 발생하는 조건들

 

- Safety

: 함수가 호출하기에 unsafe한 경우라면 이 함수가 안전하지 않은 이유와 호출자가 이 함수를 호출할 때 지켜야할 불변성에 대해 설명

 

 

테스트로서의 문서화 주석

cargo test를 실행하면 문서에 있던 예시 코드들이 테스트로서 실행됨

 

 

주석이 포함된 아이템

문서화 주석 스타일 //!은 주석 뒤에 오는 아이템을 문서화하는 것이 아닌 주석을 담고 있는 아이템을 문서화함

이러한 문서화 주석은 일반적으로 크레이트 루트파일 (관례상 src/lib.rs) 혹은 모듈에 사용하여 크레이트 혹은 모듈 전체에 대한 문서를 작성하는데 사용

//! # My Crate
//!
//! `my_crate` is a collcation of utilities to make performing certain

/// Adds one to the number given
// -- 생략 --

 

 

 

 

 

pub use로 편리하게 공개 API 내보내기

pub use를 사용하면 내부 아이템을 다시 내보내서(re-export) 기존의 비공개 구조와 다른 공개 구조를 만들 수 있음

이를 통해 다른 사람들이 다른 라이브러리에서 편리하게 사용할 수 있음 (일일이 모듈 내 요소를 찾을 필요가 없어짐)

//! # Art
//!
//! A library for modeling artistic concepts.

pub use self::kinds::PrimaryColor;
pub use self::kinds::SecondaryColor;
pub use self::utils::mix;

pub mod kinds {
    // 생략
}

pub mod utils {
    // 생략
}

use art::mix;
use art::PrimaryColor;

fn main() {
    // 생략
}

 

 

 

 

 

crates.io 계정 설정하기

크레이트를 배포하기 위해 crates.io 계정을 만들고 API 토큰을 얻을 필요가 있음

이를 위해서는 crates.io 홈페이지에서 깃허브 계정으로 로그인하여 API 키를 얻고 아래 명령을 실행

cargo login API_키

 

 

 

 

새 크레이트에 메타데이터 추가하기

[package]
name = "guessing_name"
version = "0.1.0" 
edition = "2025"
description = "greate project"
license = "MIT" # 라이선스 식별자 값

 

 

 

 

 

crates.io에 배포하기

크레이트 배포는 다른 사람들이 사용할 특정 버전을 crates.io에 올리는 것으로 영구적으로 대포됨

버전은 덮어씌워질 수 없고, 코드는 삭제될 수 없음

crates.io의 주료 목표 한 가지는 영구적인 코드 보관소로서 작동하여 crates.io의 크레이트에 의존하는 모든 프로젝트의 빌드가 계속 작동하도록 하는 것

cargo publish

 

이미 존재하는 크레이트의 새 버전을 배포하는 것은 Cargo.toml 파일의 version 값을 변경하여 cargo publish를 하면 됨

 

 

 

 

cargo yank로 crates.io에서 버전 사용하지 않게 하기

크레이트의 이전 버전을 제거할 수는 없지만 향후의 프로젝트들이 새로운 디펜던시로 추가할 수 없도록 방지할 수 있음

카고는 이를 끌어내기(yanking)이라는 기능으로 지원

버전 끌어내기는 이 버전에 의존하는 중인 모든 프로젝트들을 계속 지원하면서 새 프로젝트가 이 버전에 의존하는 것을 방지

cargo yank --vers 1.0.1

# 되돌리기
cargo yank --vers 1.0.1 --undo

 

 

 

 

 

카고 작업 공간

카고는 작업 공간이라는 기능을 제공하여 나란히 개발되는 여러 패키지를 관리하는데 도움을 줌

 

 

작업 공간 생성하기

작업 공간 (workspace)은 동일한 Cargo.lock과 출력 디렉터리를 공유하는 패키지들의 집합

아래 예시는 작업 공간에 하나의 바이너리와 두 개의 라이브러리를 담음

mkdir add
cd add
vim Cargo.toml

[workspace]

members = [
    "adder",
]

cargo new adder

 

- 최종 디렉터리 형태

add
|__Cargo.lock
|__Cargo.toml
|__adder
   |__Cargo.toml
   |__src
      |__main.rs
|__target

 

작업 공간은 컴파일된 결과가 위치할 하나의 target 디렉터리를 최상위 디렉터리에 가짐

adder 크레이트는 자신의 target 디렉터리를 가지지 않음

adder 디렉터리 내에서 cargo build를 실행해도 컴파일 결과는 add/target에 위치하게됨

이는 작업 공간 내 크레이트들이 서로 의존하기 때문임 

 

 

 

 

 

작업 공간에 패키지 추가하기

[workspace]

members = [
    "adder",
    "add_one",
]

cargo new add_one --lib

# adder/Cargo.toml
[dependencies]
add_one = { path = "../add_one" }

 

 

 

 

커스텀 명령어로 카고 확장하기

카고는 직접 카고를 수정하지 않고도 새로운 보조 명령어로 확장할 수 있게끔 설계되어 있음 

예를들어 $PATH에 있는 어떤 바이너리의 이름이 cargo-something이면 carge something이라는 명령어로 마치 카고의 보조 명령어인 것처럼 실행할 수 있음

이와 같은 커스텀 명령어들은 cargo --list를 실행할 때에 목록에도 포함됨