[태그:] crate

외부 라이브러리 사용법 (Crate 활용)

Rust는 Crate(크레이트) 단위로 코드와 라이브러리를 구성합니다.
크레이트는 Rust의 패키지 시스템에서 가장 작은 단위로, 우리가 Cargo.toml에 추가해서 사용하는 외부 라이브러리들도 모두 크레이트입니다.

크레이트의 기본 개념과 사용법, 외부 라이브러리를 프로젝트에 추가하고 사용하는 법, 그리고 버전 관리와 의존성에 대해 알아보겠습니다.

1. Crate란?

  • 크레이트(Crate)는 하나의 컴파일 단위입니다.
  • 두 가지로 나뉩니다:
    – Binary Crate: main() 함수를 포함하고, 실행 가능한 프로그램이 됨
    – Library Crate: 다른 크레이트에서 가져와 사용할 수 있는 재사용 가능한 코드 집합

예를 들어 우리가 사용하는 tokio, serde, rand 등은 모두 라이브러리 크레이트입니다.

2. Cargo로 외부 크레이트 사용하기

Rust 프로젝트는 Cargo라는 빌드 도구를 중심으로 관리됩니다.

가. Cargo.toml에 의존성(dependency) 추가

예를 들어 난수를 생성하는 rand 크레이트를 사용하려면, 프로젝트 루트의 Cargo.toml 파일의 dependencies 절에 다음과 같이 작성합니다.

처음에 버전을 0.8.0을 적었더니 버전이 0.9.1까지 있으니 여기서 선택하라고 화면이 표시됩니다.

dependency 더 높은 버전 제시
[dependencies]
rand = "0.9.1"

이제 cargo build 또는 cargo run을 실행하면 자동으로 해당 크레이트가 다운로드되고 프로젝트에 포함됩니다.

나. 코드에서 사용하기

use rand::Rng;

fn main() {
    let mut rng = rand::rng();
    let n: u8 = rng.random_range(1..=10);
    println!("1부터 10 사이의 무작위 수: {}", n);
}
use rand::Rng;
  • Rng는 random_range() 같은 메서드를 제공하는 트레잇(trait)입니다.
  • 이걸 use해야 random_range(…) 같은 메서드를 쓸 수 있습니다.
let mut rng = rand::rng();
  • 최신 rand에서는 rand::rng()로 난수 생성기를 가져옵니다.
  • 이전에는 rand::thread_rng()를 사용했지만, 그건 deprecated 되었고 이제는 rng()로 대체됩니다. rand 버전을 0.8로 하면 아래와 같은 에러가 발생합니다.
crate 버전이 낮아 오류 발생
  • 반환 타입은 여전히 내부적으로 ThreadRng입니다.

📝 의미:

“현재 스레드에서 사용할 난수 생성기를 가져와서 rng에 저장하라”

let n: u8 = rng.random_range(1..=10);
  • random_range(1..=10)은 1부터 10까지의 정수 중 무작위 값을 생성합니다.
  • inclusive range (..=)를 사용했으므로, 10도 포함됩니다.
  • 반환되는 값은 u8 타입으로 명시적으로 지정했습니다.
  • random_range는 gen_range() 대신 사용되는 최신 방식입니다.
println!(“1부터 10 사이의 무작위 수: {}”, n);
  • 생성된 난수 n을 콘솔에 출력합니다.
  • 실행할 때마다 1~10 사이의 숫자가 무작위로 나옵니다.

3. 크레이트 문서 확인하기

모든 주요 크레이트는 문서를 잘 갖추고 있습니다.
https://docs.rs에서 크레이트 이름으로 검색하면 API 문서를 확인할 수 있습니다.

예: https://docs.rs/rand

문서에는 모듈 구조, 사용 예제, Trait 설명 등이 포함되어 있어 매우 유용합니다.

4. 크레이트 버전 지정

Cargo는 Semantic Versioning을 따릅니다.

  • rand = “0.9” → 0.9.x까지 자동 업데이트 (1.0은 제외)
  • rand = “=0.9.1” → 정확한 버전
  • rand = “>=0.9, <10.0” → 범위 지정

보통은 “0.9”와 같이 호환 가능한 최신 버전으로 표시하는 것이 일반적입니다.

5. 여러 크레이트 함께 사용하기

Rust 프로젝트는 여러 외부 크레이트를 함께 사용할 수 있습니다.

예:serde와 serde_json을 함께 사용하여 JSON을 파싱:

[Cargo.toml]

[dependencies]
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"

[main.rs]

use serde::{Deserialize, Serialize};
use serde_json::Result;

#[derive(Serialize, Deserialize, Debug)]
struct Person {
    name: String,
    age: u8,
}

fn main() -> Result<()> {
    let data = r#"{"name": "홍길동", "age": 30}"#;
    let p: Person = serde_json::from_str(data)?;
    println!("{:?}", p);
    Ok(())
}

가. use 키워드

use serde::{Deserialize, Serialize};
use serde_json::Result;
  • Rust의 use 키워드는 코드에서 다른 모듈이나 라이브러리의 특정 항목(함수, 구조체, 열거형 등)을 현재 스코프(범위)로 가져와 사용하기 위해 사용됩니다. 이를 통해 코드를 더 간결하고 읽기 쉽게 만들 수 있습니다. 
  • serde::{Deserialize, Serialize}: 구조체를 직렬화(Serialize) 또는 역직렬화(Deserialize) 하려면 이 트레잇이 필요합니다.
  • serde_json::Result: serde_json이 제공하는 Result 타입(Enum)을 사용합니다. 에러 처리를 쉽게 하기 위해 사용됩니다.

나. 구조체 정의

#[derive(Serialize, Deserialize, Debug)]
struct Person {
    name: String,
    age: u8,
}
  • [derive(…)]: 구조체에 자동으로 트레잇 구현을 추가합니다.
    – Serialize: 구조체를 JSON으로 변환할 수 있게 함.
    – Deserialize: JSON을 구조체로 변환할 수 있게 함.
    – Debug: println!(“{:?}”, …)으로 구조체 내용을 출력할 수 있게 함.
  • Person 구조체 정의
    – name: 문자열 타입
    – age: u8(0~255 정수 타입)

다. main 함수

fn main() -> Result<()> {
  • 반환 타입이Result<()>인 이유는 serde_json::from_str가 실패할 수 있기 때문입니다. 실패하면 에러를 리턴하고, 성공하면 Ok(())를 반환합니다.

라. JSON 문자열 → 구조체

let data = r#"{"name": "홍길동", "age": 30}"#;
  • r#”…#”는 raw string(원시 문자열) 문법입니다. 문자열 내부에 따옴표가 있어도 별도로 이스케이프할 필요가 없어 편리합니다.
  • {“name”: “홍길동”, “age”: 30}는 JSON 포맷 문자열입니다.
let p: Person = serde_json::from_str(data)?;
  • serde_json::from_str는 JSON 문자열을 파싱해서 Person 구조체로 변환합니다.
  • ? 연산자는 실패 시 에러를 리턴하고, 성공 시 결과값을 반환합니다.

마. 구조체 출력

println!("{:?}", p);
  • 구조체 p를 Debug 포맷으로 출력합니다. 결과는 예를 들어 다음과 같이 나옵니다.
    Person { name: “홍길동”, age: 30 }

6. Crate.io에서 크레이트 찾기

외부 라이브러리는 모두 https://crates.io에서 검색할 수 있습니다.

  • 인기 순, 다운로드 수, 최근 업데이트 순으로 정렬 가능
  • 사용자 리뷰, 문서 링크, GitHub 코드도 확인 가능

예:

  • 웹 요청 라이브러리: reqwest
  • 비동기 실행기: tokio
  • CLI 도구 만들기: clap

7. 크레이트 네임스페이스(namespace)와 모듈(module)

크레이트를 임포트할 때는 보통 최상위 네임스페이스부터 시작합니다.

use regex::Regex; // regex 크레이트 내 Regex 타입 사용

내부 모듈에 접근할 땐 점(::)을 따라 구조를 확인합니다.

예:

use tokio::time::{sleep, Duration};

8. 주의사항

  • 크레이트마다 버전이 다르면 충돌이 생길 수 있음 → Cargo가 자동으로 중복 조율
  • 사용하지 않는 크레이트는 지워주는 게 좋음
  • 일부 크레이트는 feature flag를 통해 기능을 선택적으로 활성화함

9. 정리

항목설명
CrateRust 코드의 재사용 단위, 외부 라이브러리
Cargo.toml의존성을 정의하는 설정 파일
crates.io외부 크레이트 검색/다운로드 플랫폼
docs.rs모든 크레이트의 공식 문서 모음 사이트
use크레이트 또는 모듈에서 항목을 가져오는(import) 키워드

10. 마무리

Rust의 크레이트 생태계는 매우 강력하고 체계적입니다.
외부 라이브러리를 잘 활용하면, 코드의 양을 줄이고 품질을 높일 수 있습니다.
이제는 필요한 기능이 있다면 직접 구현하기보다 crates.io에서 검색해보는 것이 먼저입니다.

모듈(Module), 패키지(Package), 그리고 use 키워드

Rust 프로젝트가 커지면 코드 구조를 깔끔하게 나누는 것이 중요합니다. 따라서, 모듈과 패키지, 그리고 패키지와 크레이트의 개념에 대해서 살펴보고, pub 키워드, 하위 모듈, 파일과 모듈 연동, use 키워드에 대해서도 알아보겠습니다.

1. 모듈(Module)

  • Rust에서 모듈은 코드를 그룹화하는 단위입니다.
  • 파일이나 폴더 단위로 구성할 수 있습니다.
mod greetings {
    pub fn hello() {
        println!("안녕하세요!");
    }
}

fn main() {
    greetings::hello();
}
  • mod 키워드로 모듈을 선언합니다.
  • 함수, 변수 등을 외부에서 사용하려면 pub으로 공개(public)해야합니다.
  • main 함수에서 greetings 모듈의 hello 함수를 사용하려면 ::을 이용해서 모듈명::함수명으로 선언해야 합니다. 따라서, greetings::hello();가 됐습니다.
  • 위 코드를 실행하면 greetings 모듈의 hello 함수가 실행되어
    “안녕하세요!”가 화면에 출력됩니다.
  • fn hello() 앞의 pub를 지우고 실행하면
    hello 함수가 private라는 에러 메시지가 표시됩니다. private이기 때문에 main함수에서 불러서 사용할 수가 없는 것입니다.

2. 하위 모듈

mod greetings {
    pub mod english {
        pub fn hello() {
            println!("Hello!");
        }
    }
}

fn main() {
    greetings::english::hello();
}
  • 모듈 내에 또 다른 모듈을 정의할 수 있음
    위 코드를 보면 greetings안에 english 모듈이 있고, 그 안에 hello 함수가 있습니다.
  • 따라서, main함수에서 불러서 사용할 수 있도록 맨 위 module에만 pub이 없고, 그 안 module에는 pub이 추가되어 있고, hello 함수에 pub이 붙어 있는 것은 위와 같습니다.
  • 또한 mod 안의 mod 안에 hello 함수가 있으므로 ::을 두번 써서, greetings::english::hello();라고 함수를 호출하고 있습니다.
  • 위 코드를 실행하면 “Hello!”라고 화면에 출력됩니다.

3. 파일과 모듈 연동

  • mod로 선언한 모듈은 같은 src 폴더 내에 다른 rs 파일로 분리 가능
src/
 ├── main.rs   // 메인 파일
 └── greetings.rs  // greetings 모듈

(greetings.rs)

pub fn hello() {
    println!("안녕하세요!");
}
  • rs 파일명이 greetings이므로 파일명이 module이 돼서, greetings.rs 파일 안에는 mod 선언이 불필요하며, 함수는 공개되어야 하므로 pub를 앞에 붙여야 하고, println! 문의 내용은 같습니다.

(main.rs)

mod greetings;

fn main() {
    greetings::hello();
}
  • main.rs에서 main 함수 안이 아니라 밖에 greetings module을 불러오기 위해 mod greetings;라고 선언해야 하며, 모듈명::함수명으로 함수를 실행하는 것은 동일합니다.
  • 실행 결과는 “안녕하세요!”라고 동일합니다.
  • 아래와 같이 mod greetings;를 main함수의 아래에 배치해도 실행에 문제가 없습니다.
fn main() {
    greetings::hello();
}

mod greetings;

4. 패키지와 크레이트(Crate)

  • 패키지: 패키지는 크레이트들을 관리하고 빌드, 테스트, 배포하는 역할을 합니다. 패키지 안에는 여러 개의 바이너리 크레이트가 있을 수 있지만, 라이브러리 크레이트는 하나만 포함할 수 있습니다.
    cargo new my_project 명령으로 패키지를 생성하면, Cargo.toml 파일과 src 디렉토리가 생성되는데, src 디렉토리에는 크레이트의 소스 코드가 위치합니다. 
    Cargo.toml에서 패키지를 설정합니다.

  • 크레이트: 크레이트는 라이브러리 또는 실행 가능한 바이너리 코드를 제공하는 모듈 트리입니다. 크레이트는 모듈 시스템을 통해 코드 구조를 관리하고, 기능을 캡슐화하며, 다른 프로젝트에서 재사용될 수 있도록 합니다. 
– 바이너리 크레이트: 실행 가능한 바이너리 파일로 컴파일되는 크레이트입니다. main 함수를 포함하며, 실행 시 프로그램의 시작점이 됩니다. src/main.rs 파일이 바이너리 크레이트의 루트 역할을 합니다.
– 라이브러리 크레이트: 다른 프로젝트에서 재사용할 수 있는 코드 모음입니다. main 함수를 포함하지 않으며, 실행 파일로 컴파일되지 않습니다. src/lib.rs 파일이 라이브러리 크레이트의 루트 역할을 합니다.

5. use 키워드

  • 긴 경로를 간단히 하거나 외부 모듈을 가져올 때 사용
mod greetings {
    pub fn hello() {
        println!("안녕하세요!");
    }
}

use greetings::hello;

fn main() {
    hello();
}
  • main 함수 안에 greetings::hello();라고 표기해야 하지만,
    use greetings::hello;라고 main 함수의 밖에서 선언하면, hello();라고만 써서 함수를 간단하게 사용할 수 있습니다. hello는 중복되는 것을 주의해야 합니다.
  • 별칭(alias) 지정도 가능
use greetings::hello as say_hello;

fn main() {
    say_hello();
}
  • 별칭을 지정하면 별칭으로 함수명을 사용하면 됩니다.
  • mod와 use 키워드를 함께 사용 가능합니다.
    아래와 같이 mod greetings;로 greetins.rs 파일을 불러들인 후 use 키워드를 사용해 함수를 호출 할 수 있습니다.

mod greetings;
use greetings::hello as say_hello;

6. 요약

개념설명
mod모듈 선언, 코드 그룹화
pub공개 키워드, 외부 접근 허용(cf. private)
파일 분리mod greetings;와 greetings.rs
패키지/크레이트프로젝트 단위, 컴파일 단위
use모듈 경로 단축 및 별칭 지정