[RUST] 러스트 프로그래밍 공식 가이드(제2판) 14장 요약

릴리스 프로필을 통한 빌드 커스터마이징하기

• 릴리스 프로필이란 설정값을 가지고 있는 미리 정의된 커스터마이징 가능한 프로필을 말하며, 이 설정값으로 프로그래머는 코드 컴파일을 위한 다양한 옵션을 제어할 수 있음
  • dev 프로필([profile.dev]) : cargo build를 실행할 때 사용
  • release 프로필([profile.release]) : cargo build --release를 실행할 때 사용
• Cargo.toml 파일에 [profile.*]섹션을 명시적으로 추가하지 않았을 경우 적용ㅇ되는 각 프로필의 기본 설정이 있고, 커스터마이징을 원하는 프로필에 대해 [profile.*] 섹션을 추가하면 이 기본 설정을 덮어씌울 수 있음

crates.io에 크레이트 배포하기

유용한 문서화 주석 만들기

• 러스트에는 문서화 주석 이라고 불리는 문서화를 위한 특별한 종류의 주석이 있으며 이 주석은 HTML 문서를 생성함
  • 이 HTML 문서에는 크레이트를 어떻게 사용하는지에 관심이 있는 프로그래머들을 위하여 공개 API 아이템들에 대한 문서화 주석 내용을 보여줌
• 문서화 주석은 슬래시 3개(///)를 이용하며 텍스트 서식을 위한 마크다운 표기법을 지원
• cargo doc을 실행해 문서화 주석으로부터 HTML 문서를 생성할 수 있으며, 이 명령어는 러스트와 함께 배포된 rustdoc 도구를 실행하여 생성된 HTML 문서를 target/doc 디렉터리에 넣음

크레이트 저자가 문서에서 자주 사용하는 절

• Panics : 문서화된 함수가 패닉을 일으킬 수 있는 시나리오를 설명
• Errors : 해당 함수가 Result를 반환하는 경우에 발생할 수 있는 에러의 종류와 해당 에러들이 발생하는 조건을 설명
• Safety : 함수가 호출하기에 unsafe한 경우라면, 이 함수가 안전하지 않은 이유와 호출자가 이 함수를 호출할 때 지켜야 할 불변성에 대해 설명

테스트로서의 문서화 주석

• 문서화 주석에 작성한 예시 코드는 cargo test 실행 시 테스트로서 실행되고 테스트 결과 절을 확인할 수 있음

주석이 포함된 아이템

• 문서화 주석 스타일 //!은 주석을 담고있는 아이템을 문서화
• 문서화 주석은 일반적으로 크레이트 루트 파일 혹은 모듈에 사용하여 크레이트 혹은 모듈 전체에 대한 문서를 작성하는데 사용
• cargo doc --open을 실행하면 문서 첫 페이지 내용 중 크레이트의 공개 아이템 목록 상단에 이 주석의 내용이 나타남

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

• 크레이트 내부가 구조가 모듈로 논리적으로 잘 잡혀있다면 사용자 입장에서는 구조가 너무 깊어 불편을 겪을 수 있는데 이를 해결하기 위해 pub use를 이용하여내부 아이템을 다시 내보내서 내부 구조는 그대로 두되, 외부에 보이는 공개 API 만을 단순화할 수 있음
• cargo doc이 생성한 크레이트의 API 문서에는 다시 내보내진 아이템(Re-exports)을 첫 화면의 목록에 보여주고 링크를 걸어줌

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

• crates.io 에 올라갈 크레이트의 이름은 선착순으로 배정되며 중복된 이름으로 크레이트를 배포할 수 없므로 Cargo.toml 파일의 [package] 섹션의 name 필드 변경하여 크레이트명이 중복되지 않도록 지정
• cargo publish를 실행해 크레이트를 배포할 수 있으며, 설명과 라이선스 필드 정보는 필수 입력으로 이 값으 없다면 에러를 발생함 (license 필드는 라이선스 식별자 값이 필요하며 SPDX에 이 값으로 사용할 수 있는 식별자 목록이 있음)

crates.io에 배포하기

• 크레이트 배포는 다른 사람들이 사용할 특정 버전을 crates.io 에 올리는 것을 의미하며 버전은 덮어씌워질 수 없고, 코드는 삭제될 수 없으며 배포는 영구적임

이미 존재하는 크레이트의 새 버전 배포하기

• 크레이트를 변경하여 새 버전을 배포할 준비가 되었다면 Cargo.toml 파일의 version 필드 값을 바꾸고 cargo publish 를 실행하여 새 버전을 배포

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

• Crates.io에 올라간 특정 버전의 크레이트가 깨졌거나 문제가 있을때, 새 프로젝트에서 사용되지 않게 막는 기능이 있으며 이를 끌어내기(yanking) 라고 함(크레이트가 삭제되는 것이 아닌 새로 사용하지 못하게 막는 명령)
• 버전 끌어내기는 Cargo.lock이 있는 모든 기존 프로젝트에서는 계속 빌드가 가능하며 새로운 프로젝트에서는 Cargo.lock 파일에 끌어내려진 버전을 사용할 수 없음
• 추후 끌어내기를 되돌려 다른 프로젝트들이 다시 해당 버전에 대해 의존을 허용하려면 cargo yarnk --vers 1.0.1 --undo 와 같이 명령어에 --undo 를 추가해 주어야 함

카고 작업 공간

• 라이브러리 크레이트가 점점 커져 패키지를 여러 개의 라이브러리 크레이트로 분리하고싶을 때, 카고는 작업 공간이라는 기능을 제공하여 나란히 개발되는 여러 관련 패키지를 관리하는데 도움을 줌

작업 공간 생성하기

• 작업 공간(workspace)은 동일한 Cargo.lock과 출력 디렉터리를 공유하는 패키지들의 집합을 말하며, 작업 디렉터리를 생성하고 작업 디렉터리 내에 Cargo.toml 을 생성하여 전체 작업 공간에 대한 설정을 함
• 작업 디렉터리 내의 Cargo.toml 파일에는 [package] 섹션이 없고, [workspace] 섹션으로 시작하여 크레이트 패키지에 대한 경로를 명시하는 방식으로 이 작업 공간에 멤버를 추가
• 작업 디렉터리에서 cargo build 를 수행하면 컴파일 결과가 위치할 하나의 target 디렉터리를 최상위 디렉터리에 가짐 (각 크레이트는 자신의 target 별도 디렉터리를 갖지 않고 최상위 디렉터리의 target을 공유)
• 카고는 작업 공간 내의 크레이트들이 서로 의존할 것이라고 가정하지 않으므로, 디펜던시 관계에 대해 명시해줌 (바이너리 크레이트의 Cargo.toml 에 라이브러리 크레이트의 경로 디펜던시를 추가)
• 작업 디렉터리의 최상위에서 바이너리 크레이트를 실행하기 위해서는 cargo run 에 -p 인수와 패키지명을 써서 작업 공간 내의 어떤 패키지를 실행하고 싶은지 지정

작업 공간에서 외부 패키지 의존하기

• 작업 공간에는 각 크레이트 디렉터리마다 Cargo.lock 이 생기지 않고, 최상위에 하나의 Cargo.lock 이 생기는데 이로 인해 모든 크레이트가 모든 디펜던시에 대해 같은 버전을 사용함을 보증함 (작업 공간 내 모든 크레이트가 동일한 디펜던시를 사용하도록 만드는 것은 이 크레이트들이 항상 서로 호환될 것임을 뜻함)
• 만약 adder/Cargo.toml과 add_one/Cargo.toml 에 rand 패키지를 추가하면 카고는 이 둘을 하나의 rand 버전으로 결정하여 하나의 Cargo.lock 에 기록

작업 공간에 테스트 추가하기

• 작업 디렉터리 최상위에서 cargo test를 실행한다면 작업 공간의 모든 크레이트에 대한 테스트를 수행
• -p플로그와 테스트하고자 하는 크레이트의 이름을 명시하면 최상위 디렉터리에서 작업 공간에 있는 특정 크레이트에 대한 테스트를 실행할 수 있음

cargo install로 creates.io에 있는 바이너리 설치하기

• cargo install명령어는 로컬 환경에 바이너리 크레이트를 설치하고 사용할 수 있도록 해줌. 단, 바이너리 타깃을 가진 패키지만 설치할 수 있음에 주의 (러스트 개발자들이 crates.io에서 공유하고 있는 도구를 편리하게 설치할 수 있도록 하기 위함)
  • 바이너리 타깃이란 src/main.rs 파일 혹은 따로 바이너리로 지정된 파일을 가진 크레이트가 생성해낸 실행 가능한 프로그램을 말하는 것
• cargo install을 이용해 설치된 모든 바이너리는 설치 루트의 bin 디렉터리에 저장 됨

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

• 카고는 직접 카고를 수정하지 않고도 새로운 보조 명령어로 확장할 수 있게끔 설계됨
• $PATH에 있는 어떤 바이너리의 이름이 cargo-something 이라면, cargo something이라는 명령어로 마치 카고의 보조 명령어인 것 처럼 실행할 수 있음
• 커스텀 명령어들은 cargo --list 를 실행할 때 목록에 포함됨