Rust 빌드 및 테스트

Rust 프로젝트를 자동으로 빌드하고 테스트하는 지속적 통합(CI) 워크플로우를 만드는 방법을 알려드릴게요. 이 가이드를 따라 하면 Rust 패키지를 빌드하고, 테스트하고, 게시하는 워크플로우를 직접 구성할 수 있어요.

출처: 문서

본문

Introduction

이 가이드에서는 Rust 패키지를 빌드하고, 테스트하고, 게시하는 방법을 보여드릴게요.

GitHub에서 호스팅하는 러너에는 사전 설치된 소프트웨어가 담긴 도구 캐시(tools cache)가 있어서, Rust의 의존성도 포함되어 있답니다. 최신 소프트웨어 전체 목록과 사전 설치된 Rust 버전을 보려면 GitHub-hosted runners 문서를 확인해 주세요.

Prerequisites

YAML 문법과 GitHub Actions에서 YAML을 사용하는 방법을 이미 알고 계신다면 좋아요. 자세한 내용은 Workflow syntax for GitHub Actions 문서를 참고하세요.

Rust 언어에 대한 기본적인 이해가 있으면 더 좋아요. 자세한 내용은 Getting started with Rust 문서를 참고하세요.

Using a Rust workflow template

빠르게 시작하고 싶다면, 저장소의 .github/workflows 디렉터리에 워크플로우 템플릿을 추가해 보세요.

GitHub는 대부분의 기본적인 Rust 프로젝트에 맞게 동작하는 Rust 워크플로우 템플릿을 제공해요. 이 가이드의 뒷부분에서 이 워크플로우 템플릿을 커스터마이즈하는 방법을 예시와 함께 보여드릴게요.

GitHub에서 저장소의 메인 페이지로 이동하세요.
저장소 이름 아래에서 Actions을 클릭하세요.
저장소에 워크플로우가 이미 있다면 New workflow를 클릭하세요.
"Choose a workflow" 페이지에는 추천 워크플로우 템플릿 목록이 표시돼요. "Rust"를 검색해 보세요.
Continuous integration을 클릭해서 워크플로우 목록을 필터링하세요.
"Rust - by GitHub Actions" 워크플로우에서 Configure를 클릭하세요.
필요에 따라 워크플로우를 수정하세요. 예를 들어 Rust 버전을 변경할 수 있어요.
Commit changes를 클릭하세요.

그러면 rust.yml 워크플로우 파일이 저장소의 .github/workflows 디렉터리에 추가돼요.

Specifying a Rust version

GitHub에서 호스팅하는 러너에는 최신 Rust 툴체인이 포함되어 있어요. rustup을 사용해서 러너에 설치된 버전을 확인하고, 버전을 변경하고, 다른 툴체인을 설치할 수 있답니다. 자세한 내용은 The rustup book 문서를 참고하세요.

다음 예시는 러너 환경을 Rust nightly 빌드로 설정하고 버전을 확인하는 데 사용할 수 있는 단계를 보여줘요.

      - name: Temporarily modify the rust toolchain version
        run: rustup override set nightly
      - name: Output rust version for educational purposes
        run: rustup --version

Caching dependencies

Cache 액션을 사용해서 의존성을 캐시하고 복원할 수 있어요. 다음 예시는 저장소에 Cargo.lock 파일이 있다고 가정한답니다.

      - name: Cache
        uses: actions/cache@v4
        with:
          path: |
            ~/.cargo/registry
            ~/.cargo/git
            target
          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}

캐싱에 대한 별도의 요구사항이 있거나 더 세밀한 제어가 필요하다면, cache 액션의 다른 구성 옵션을 살펴보세요. 자세한 내용은 Dependency caching reference 문서를 참고하세요.

Building and testing your code

로컬에서 코드를 빌드하고 테스트할 때 쓰는 명령을 그대로 사용할 수 있어요. 다음 예시 워크플로우는 한 job에서 cargo build와 cargo test를 사용하는 방법을 보여줍니다:

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        BUILD_TARGET: [release] # refers to a cargo profile
    outputs:
      release_built: ${{ steps.set-output.outputs.release_built }}
    steps:
      - uses: actions/checkout@v6
      - name: Build binaries in "${{ matrix.BUILD_TARGET }}" mode
        run: cargo build --profile ${{ matrix.BUILD_TARGET }}
      - name: Run tests in "${{ matrix.BUILD_TARGET }}" mode
        run: cargo test --profile ${{ matrix.BUILD_TARGET }}

이 예시에서 사용된 release 키워드는 cargo profile에 해당해요. Cargo.toml 파일에 정의한 어떤 profile이든 사용할 수 있어요.

Publishing your package or library to crates.io

코드를 빌드하고 테스트하는 워크플로우를 구성했다면, 이제 secret을 사용해서 crates.io에 로그인하고 패키지를 게시할 수 있어요.

      - name: Login into crates.io
        run: cargo login ${{ secrets.CRATES_IO }}
      - name: Build binaries in "release" mode
        run: cargo build -r
      - name: "Package for crates.io"
        run: cargo package # publishes a package as a tarball
      - name: "Publish to crates.io"
        run: cargo publish # publishes your crate as a library that can be added as a dependency

크레이트를 빌드하거나 패키징할 때 오류가 발생한다면, 매니페스트 Cargo.toml 파일의 메타데이터를 확인해 보세요. The Manifest Format 문서를 참고하세요. 또한 Cargo.lock 파일도 확인해야 해요. Cargo.toml vs Cargo.lock 문서를 참고하세요.

Packaging workflow data as artifacts

워크플로우가 완료된 후에는 결과물을 아티팩트로 업로드해서 분석에 사용하거나 다른 워크플로우에서 사용할 수 있어요. 다음 예시 단계를 워크플로우에 추가해서 다른 워크플로우에서 사용할 애플리케이션을 업로드해 보세요.

      - name: Upload release artifact
        uses: actions/upload-artifact@v4
        with:
          name: <my-app>
          path: target/${{ matrix.BUILD_TARGET }}/<my-app>

업로드한 아티팩트를 다른 job에서 사용하려면 워크플로우가 저장소에 대한 올바른 권한을 갖도록 설정해야 해요. Use GITHUB_TOKEN for authentication in workflows 문서를 참고하세요. 다음 예시 단계를 사용해서 이전 워크플로우에서 만든 앱을 다운로드하고 GitHub에 게시할 수 있어요.

      - uses: actions/checkout@v6
      - name: Download release artifact
        uses: actions/download-artifact@v5
        with:
          name: <my-app>
          path: ./<my-app>
      - name: Publish built binary to GitHub releases
      - run: |
          gh release create --generate-notes ./<my-app>/<my-project>#<my-app>

Rust 빌드 및 테스트