컴파일러를 빌드하고 실행하는 방법

컴파일러는 bootstrap이라는 도구를 사용하여 빌드합니다. 이 도구를 실행하려면 Python이 설치되어 있어야 합니다.

빠른 시작

컴파일러를 실행하는 과정을 더 간단히 다루는 빠른 시작 안내는 빠른 시작을 참조하십시오.

소스 코드 받기

메인 저장소는 rust-lang/rust입니다. 이 저장소에는 컴파일러, 표준 라이브러리(core, alloc, test, proc_macro 등 포함), 그리고 여러 도구(예: rustdoc, 부트스트래핑 인프라 등)가 들어 있습니다.

rustc 작업을 시작하는 가장 첫 단계는 저장소를 클론하는 것입니다:

git clone https://github.com/rust-lang/rust.git
cd rust

참고: Windows에서는 대규모 체크아웃의 경우 백신 검사로 인해 Git 및 빌드 명령이 눈에 띄게 느려질 수 있습니다. 그런 경우에는 Rust 체크아웃 디렉터리만 Windows 보안 제외 목록에 추가하는 것을 고려하십시오. 필요 이상으로 넓은 범위를 제외 항목으로 추가하지 마십시오.

저장소 부분 클론하기

저장소의 크기 때문에 느린 인터넷 연결에서는 클론하는 데 오랜 시간이 걸릴 수 있으며, 모든 파일과 디렉터리의 전체 이력을 저장할 디스크 공간도 필요합니다. 대신 git에 부분 클론을 수행하도록 지시할 수 있습니다. 이 경우 현재 파일 내용만 완전히 가져오고, 예를 들어 이력의 과거 시점으로 이동할 때 추가 파일 내용을 자동으로 가져옵니다. 모든 git 명령은 평소와 같이 계속 동작하지만, 아직 불러오지 않은 이력 시점을 방문하려면 인터넷 연결이 필요하다는 대가가 따릅니다.

git clone --filter='blob:none' https://github.com/rust-lang/rust.git
cd rust

참고: 이 링크에서는 이러한 유형의 체크아웃을 더 자세히 설명하고, 얕은 클론과 같은 다른 방식과도 비교합니다.

저장소 얕은 클론하기

부분 클론보다 오래된 대안으로 저장소를 얕은 클론하는 방법이 있습니다. 이렇게 하려면 git clone 명령에 --depth N 옵션을 사용하면 됩니다. 이 옵션은 git에 “얕은 클론“을 수행하도록 지시하여, 저장소를 클론하되 마지막 N개의 커밋까지만 남기고 잘라냅니다.

--depth 1을 전달하면 git은 저장소를 클론하되 이력을 main 브랜치의 최신 커밋까지만 남기고 잘라내며, 소스 코드를 살펴보거나 컴파일러를 빌드하는 데는 대개 이것으로 충분합니다.

git clone --depth 1 https://github.com/rust-lang/rust.git
cd rust

참고: 얕은 클론을 사용하면 실행할 수 있는 git 명령이 제한됩니다. 컴파일러 작업에 참여하고 기여할 계획이라면 일반적으로 위에 나온 대로 저장소 전체를 클론하거나 대신 부분 클론을 수행할 것을 권장합니다.

예를 들어 git bisect와 git blame은 커밋 기록에 접근해야 하므로 저장소를 --depth 1로 클론한 경우에는 작동하지 않습니다.

bootstrap이란 무엇입니까?

bootstrap은 rust 저장소의 빌드 도구입니다. bootstrap으로 문서를 빌드하고, 테스트를 실행하고, 컴파일러와 표준 라이브러리를 빌드할 수 있습니다.

이 장에서는 생산적으로 작업하는 데 필요한 기본 사항을 중점적으로 다룹니다. bootstrap에 대해 더 알고 싶다면 이 장을 읽으십시오.

bootstrap 실행하기

bootstrap은 대부분의 시스템(Unix, 설정된 경우 Windows)에서 다음과 같이 실행할 수 있습니다.

./x <subcommand> [flags]

이 문서와 예제는 이 방법으로 bootstrap을 실행한다고 가정합니다. 다른 실행 방법은 다음과 같습니다.

# In Windows PowerShell (if PowerShell is configured to run scripts)
./x <subcommand> [flags]
# In NuShell (if PowerShell is configured to run scripts). `./x` does not work in NuShell if `.py` files are not configured to run Python.
./x.ps1 <subcommand> [flags]

# On the Windows Command Prompt (if .py files are configured to run Python)
x.py <subcommand> [flags]

# You can also run Python yourself, e.g.:
python x.py <subcommand> [flags]

# On a Unix shell if you have `python3` but an `sh` that doesn't support `local`, e.g. on Solaris
./x.py <subcommand> [flags]

Windows에서는 PowerShell 명령을 실행할 때 다음과 같은 오류가 발생할 수 있습니다.

PS C:\Users\vboxuser\rust> ./x
./x : File C:\Users\vboxuser\rust\x.ps1 cannot be loaded because running scripts is disabled on this system. For more
information, see about_Execution_Policies at https://go.microsoft.com/fwlink/?LinkID=135170.
At line:1 char:1
+ ./x
+ ~~~
    + CategoryInfo          : SecurityError: (:) [], PSSecurityException
    + FullyQualifiedErrorId : UnauthorizedAccess

PowerShell이 로컬 스크립트를 실행하도록 허용하면 이 오류를 피할 수 있습니다.

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

bootstrap을 조금 더 편리하게 실행하기

bootstrap을 감싸는 x라는 바이너리가 있습니다. 이 바이너리는 ./x를 실행하며, 시스템 전역에 설치해 체크아웃의 어느 하위 디렉터리에서든 실행할 수 있습니다. 또한 사용할 적절한 Python 버전을 찾아 주며, 현재 사용 중인 셸에 의존하지 않습니다.

cargo install --locked --path src/tools/x로 설치할 수 있습니다.

bootstrap.toml 만들기

먼저 ./x setup을 실행하고 compiler 기본값을 선택하십시오. 그러면 몇 가지 초기화 작업을 수행하고 적절한 기본값으로 bootstrap.toml을 만들어 줍니다. 다른 기본값을 사용한다면(rustdoc처럼 컴파일러가 아닌 rust의 다른 영역에 기여하려는 경우라면 그렇게 하게 될 가능성이 높습니다) 기본값에 따라 빌드 과정이 다를 수 있으므로 해당 기본값에 대한 정보(src/bootstrap/defaults에 있음)를 반드시 읽으십시오.

또는 bootstrap.toml을 직접 작성할 수도 있습니다. 사용 가능한 모든 설정과 각 설정의 역할은 bootstrap.example.toml을 참고하십시오. 자주 변경하는 설정은 src/bootstrap/defaults를 참고하십시오.

이미 rustc를 빌드한 뒤 LLVM 관련 설정을 변경했다면 이후의 설정 변경 사항을 적용하기 위해 ./x clean --all을 실행해야 할 수도 있습니다. ./x clean을 실행해도 LLVM은 다시 빌드되지 않는다는 점에 유의하십시오.

자주 쓰는 x 명령

다음은 rustc, std, rustdoc 및 기타 도구를 작업할 때 가장 자주 사용하는 x 명령의 기본 사용법입니다.

이 명령들은 위에 적힌 그대로 사용해도 무난한 출발점입니다. 하지만 각 명령에는 본격적인 개발 작업을 위해 익혀 둘 만한 추가 옵션과 인자가 있습니다. 특히 ./x build와 ./x test는 코드의 일부만 컴파일하거나 테스트하는 다양한 방법을 제공하므로 시간을 크게 절약할 수 있습니다.

또한 x는 compiler, library, src/tools 디렉터리에 대해 모든 종류의 경로 접미사를 지원한다는 점에 유의하십시오. 따라서 x test src/tools/tidy 대신 간단히 x test tidy를 실행할 수 있습니다. 또는 x build library/std 대신 x build std를 실행할 수 있습니다.

자세한 내용은 테스트 및 rustdoc에 관한 장을 참고하십시오.

컴파일러 빌드하기

빌드에는 비교적 많은 저장 공간이 필요하다는 점에 유의하십시오. 컴파일러를 빌드하려면 10기가바이트에서 15기가바이트 이상의 여유 공간을 확보해 두는 것이 좋습니다.

bootstrap.toml을 만들었다면 이제 x를 실행할 준비가 된 것입니다. 여기에는 많은 옵션이 있지만, 로컬 컴파일러를 빌드할 때 가장 기본으로 쓰기 좋은 명령부터 시작해 봅시다:

./x build library

이 명령이 하는 일은 다음과 같습니다:

• stage0 컴파일러와 stage0 std를 사용하여 rustc를 빌드합니다.
• 방금 빌드한 stage1 컴파일러로 library(표준 라이브러리)를 빌드합니다.
• stage1 컴파일러와 stage1 표준 라이브러리를 포함하는, 동작하는 stage1 sysroot를 구성합니다.

다른 Rust 프로그램을 빌드하는 데 필요한 것이 바로 이 최종 결과물(stage1 컴파일러 + 그 컴파일러로 빌드한 라이브러리)입니다(#![no_std]나 #![no_core]를 사용하는 경우는 제외합니다).

stage1 std를 빌드하는 과정이 병목이 된다고 느끼실 수도 있지만 걱정하지 마십시오. (편법이긴 하지만) 우회 방법이 있습니다… std 재빌드 피하기에 관한 절을 참고하십시오.

때로는 전체 빌드가 필요하지 않습니다. 메서드 이름을 바꾸거나 어떤 함수의 시그니처를 변경하는 것과 같은 일종의 “타입 기반 리팩터링“을 할 때에는 대신 ./x check를 사용하여 훨씬 빠르게 빌드할 수 있습니다.

이 명령 전체는 전체 rustc 빌드의 일부만 수행한다는 점에 유의하십시오. 전체 rustc 빌드(./x build --stage 2 rustc를 실행하면 얻는 것)에는 훨씬 더 많은 단계가 있습니다:

• stage1 컴파일러로 rustc를 빌드합니다.
  • 여기서 만들어지는 컴파일러를 “stage2” 컴파일러라고 하며, 이 컴파일러는 이전 명령에서 만든 stage1 std를 사용합니다.
• stage2 컴파일러로 librustdoc과 그 밖의 여러 가지를 빌드합니다.

이 작업을 해야 하는 경우는 거의 없습니다.

특정 컴포넌트 빌드하기

표준 라이브러리를 작업하고 있다면 다른 기본 컴포넌트를 모두 빌드할 필요는 없을 것입니다. 대신 다음과 같이 이름을 지정하여 특정 컴포넌트를 빌드할 수 있습니다:

./x build --stage 1 library

x setup을 실행할 때 library 프로필을 선택했다면 --stage 1을 생략할 수 있습니다(이것이 기본값입니다).

도구를 빌드하려면 다음을 사용할 수 있습니다:

./x build src/tools/cargo

도구 테스트에 관한 절도 확인해 보십시오.

rustup 툴체인 만들기

rustc를 성공적으로 빌드하고 나면 build 디렉터리에 여러 파일이 생성되어 있을 것입니다. 이렇게 만들어진 rustc를 실제로 실행하려면 rustup 툴체인을 만드는 것을 권장합니다. 아래에 나열된 첫 번째 명령은 위의 단계에서 빌드한 stage1 툴체인을 stage1이라는 이름으로 만듭니다. 두 번째 명령은 stage1 컴파일러를 사용하여 stage2 툴체인을 만듭니다. 이는 나중에 전체 테스트 스위트를 실행할 때 필요하지만, 이 페이지에서는 빌드하지 않습니다. stage2 빌드는 stage1과 같은 ./x build 명령으로 하되, 스테이지를 2로 지정하면 됩니다.

rustup toolchain link stage1 build/host/stage1
rustup toolchain link stage2 build/host/stage2

이제 빌드한 rustc를 툴체인을 통해 실행할 수 있습니다. -vV로 실행하면 -dev로 끝나는 버전 번호가 표시되며, 이는 로컬 환경에서 빌드했음을 나타냅니다:

$ rustc +stage1 -vV
rustc 1.48.0-dev
binary: rustc
commit-hash: unknown
commit-date: unknown
host: x86_64-unknown-linux-gnu
release: 1.48.0-dev
LLVM version: 11.0

rustup 툴체인은 build 디렉터리에서 컴파일된 지정 툴체인을 가리키므로, 해당 툴체인/스테이지에 대해 x build나 x test를 실행할 때마다 rustup 툴체인도 갱신됩니다.

참고: 여기서 빌드한 툴체인에는 cargo가 포함되어 있지 않습니다. 이 경우 rustup은 설치된 nightly, beta, stable 툴체인(이 순서대로)의 cargo를 대신 사용합니다. 불안정한 cargo 플래그를 사용해야 한다면, 아직 실행하지 않았을 경우 반드시 rustup install nightly를 실행하십시오. 사용자 정의 툴체인에 관한 rustup 문서를 참고하십시오.

참고: rust-analyzer와 IntelliJ Rust 플러그인은 절차적 매크로를 다루기 위해 rust-analyzer-proc-macro-srv라는 컴포넌트를 사용합니다. 프로젝트에 사용자 정의 툴체인을 사용하려 한다면(예: rustup override set stage1을 통해) 이 컴포넌트를 빌드하는 것이 좋습니다:

./x build proc-macro-srv-cli

교차 컴파일용 타깃 빌드하기

다른 타깃으로 교차 컴파일할 수 있는 컴파일러를 만들려면 x build에 target 플래그를 원하는 만큼 전달하십시오. 예를 들어 호스트 플랫폼이 x86_64-unknown-linux-gnu이고 교차 컴파일 타깃이 wasm32-wasip1이라면 다음과 같이 빌드할 수 있습니다:

./x build --target x86_64-unknown-linux-gnu,wasm32-wasip1

만들어진 컴파일러로 절차적 매크로나 빌드 스크립트가 포함된 크레이트를 빌드하려면, 호스트 플랫폼(이 경우 x86_64-unknown-linux-gnu)에 대한 타깃 지원을 반드시 명시적으로 빌드해야 한다는 점에 유의하십시오.

x build에 플래그를 전달하지 않고도 항상 다른 타깃용으로 빌드하려면 bootstrap.toml의 [build] 섹션에서 다음과 같이 설정할 수 있습니다:

build.target = ["x86_64-unknown-linux-gnu", "wasm32-wasip1"]

일부 타깃용으로 빌드하려면 외부 의존성이 설치되어 있어야 한다는 점에 유의하십시오(예: musl 타깃을 빌드하려면 musl의 로컬 사본이 필요합니다). 타깃별 설정(예: musl 로컬 사본의 경로)은 모두 bootstrap.toml에서 제공해야 합니다. 타깃별 설정 키에 관한 정보는 bootstrap.example.toml을 참고하십시오.

타깃을 빌드하는 데 필요한 전체 구성의 예시를 보려면 rustc 책을 방문하여 왼쪽의 “Platform Support” 제목 아래에서 원하는 타깃을 선택한 다음, 해당 타깃용 컴파일러 빌드에 관한 섹션을 참고하십시오. rustc 책에 해당 페이지가 없는 타깃이라면, Rust 인프라가 교차 컴파일을 설정하고 구성하는 데 직접 사용하는 Dockerfile을 살펴보는 것이 도움이 될 수 있습니다.

이전 섹션의 안내에 따라 rustup 툴체인을 만들었다면, 컴파일러를 빌드한 뒤 다음과 같이 교차 컴파일에 사용할 수 있습니다:

cargo +stage1 build --target wasm32-wasip1

기타 x 명령

다음은 그 밖에 유용한 x 명령입니다. 이 중 일부는 다른 섹션에서 자세히 다룹니다:

• 빌드:
  • ./x build – std까지만이 아니라 전체를 stage 1 컴파일러로 빌드합니다
  • ./x build --stage 2 – rustdoc를 포함한 전체를 stage 2 컴파일러로 빌드합니다
• 테스트 실행(자세한 내용은 테스트 실행 섹션을 참고하십시오):
  • ./x test library/std – std의 단위 테스트와 통합 테스트를 실행합니다
  • ./x test tests/ui – ui 테스트 스위트를 실행합니다
  • ./x test tests/ui/const-generics - ui 테스트 스위트의 const-generics/ 하위 디렉터리에 있는 모든 테스트를 실행합니다
  • ./x test tests/ui/const-generics/const-types.rs - ui 테스트 스위트에서 const-types.rs 테스트 하나만 실행합니다

빌드 디렉터리 정리

가끔은 처음부터 다시 시작해야 할 때도 있지만, 보통은 그럴 필요가 없습니다. 이 작업이 필요하다면 bootstrap이 제대로 동작하지 않고 있을 가능성이 높으므로, 무엇이 잘못되었는지 버그로 보고해야 합니다. 정말로 모두 정리해야 한다면 명령 하나만 실행하면 됩니다!

./x clean

rm -rf build로도 되지만, 이 경우 LLVM을 다시 빌드해야 하며 빠른 컴퓨터에서도 시간이 오래 걸릴 수 있습니다.

디스크 공간에 관한 참고 사항

컴파일러를 빌드하려면(특히 stage 1을 넘어서는 경우) 상당한 여유 디스크 공간이 필요하며, 100GB 정도가 필요할 수도 있습니다. rust-analyzer용 빌드 디렉터리(예: build-rust-analyzer)를 따로 두고 있다면 필요한 공간은 더 늘어납니다. 사용자마다 디스크 할당량이 정해져 있는 dev-desktop에서는 이 한도에 쉽게 도달하지만, 로컬 개발 환경에도 똑같이 해당됩니다. 때때로 다음 작업이 필요할 수 있습니다:

• build/ 디렉터리를 삭제하십시오.
• build-rust-analyzer/ 디렉터리를 삭제하십시오(rust-analyzer용 빌드 디렉터리를 따로 두고 있는 경우).
• cargo-bisect-rustc를 사용한다면 필요 없는 툴체인을 제거하십시오. 설치된 툴체인은 rustup toolchain list로 확인할 수 있습니다.