빌드 백엔드

개요

빌드 백엔드(build backend)는 소스 트리를 소스 배포판 또는 휠로 변환합니다. uv는 PEP 517을 준수하는 모든 백엔드를 지원하며, 성능과 사용자 경험에 최적화된 네이티브 uv_build 백엔드를 제공합니다.

빌드 백엔드 선택

uv 빌드 백엔드는 최소한의 설정만 필요한 합리적인 기본값으로 대부분의 Python 프로젝트에 적합합니다. 프로젝트 메타데이터를 검증하고 uv와 긴밀하게 통합되며 속도를 우선시합니다. 단, 현재 순수 Python 코드만 지원하므로 확장 모듈에는 hatchling 등의 대체 백엔드가 필요합니다.

uv 빌드 백엔드 사용

pyproject.toml에 다음을 추가합니다:

[build-system]
requires = ["uv_build>=0.11.24,<0.12"]
build-backend = "uv_build"

새 프로젝트의 경우 uv init을 사용하면 백엔드가 자동으로 설정됩니다.

번들된 빌드 백엔드

uv 실행 파일에는 번들된 빌드 백엔드 사본이 포함되어 있으며, 버전이 호환되는 경우 uv build 작업 중에 사용됩니다. python -m build와 같은 다른 빌드 프런트엔드는 게시된 uv_build 패키지를 사용합니다.

모듈

패키지는 하나 이상의 Python 모듈(__init__.py가 있는 디렉터리)을 예상합니다. 기본 구조는 다음과 같습니다:

pyproject.toml
src
└── foo
    └── __init__.py

패키지 이름은 소문자로 변환하고 점/대시를 밑줄로 교체하여 정규화됩니다. module-name 및 module-root 설정으로 커스터마이즈합니다:

[tool.uv.build-backend]
module-name = "FOO"
module-root = ""

네임스페이스 패키지

네임스페이스 패키지는 module-name에 점을 사용합니다. foo.bar 모듈의 경우:

pyproject.toml
src
└── foo
    └── bar
        └── __init__.py

설정:

[tool.uv.build-backend]
module-name = "foo.bar"

여러 루트 모듈의 경우:

[tool.uv.build-backend]
module-name = ["foo", "bar"]

복잡한 네임스페이스에는 namespace = true를 사용합니다:

[tool.uv.build-backend]
namespace = true

스텁 패키지

타입 스텁 패키지는 -stubs 접미사와 __init__.pyi 파일을 사용합니다:

pyproject.toml
src
└── foo-stubs
    └── __init__.pyi

파일 포함 및 제외

백엔드는 어떤 파일을 배포판에 패키지할지 결정합니다. 제외는 포함보다 우선합니다.

소스 배포판 포함 항목:

• pyproject.toml
• tool.uv.build-backend.module-root 아래의 모듈
• project.license-files 및 project.readme의 파일
• tool.uv.build-backend.data 아래의 디렉터리
• tool.uv.build-backend.source-include와 일치하는 파일

기본 제외: __pycache__, *.pyc, *.pyo

휠 포함 항목:

• tool.uv.build-backend.module-root 아래의 모듈
• project.license-files의 파일(.dist-info에 복사)
• project.readme(메타데이터에 복사)
• tool.uv.build-backend.data 아래의 디렉터리(.data에 복사)

포함 및 제외 구문

포함은 고정(anchored)됩니다. pyproject.toml은 <root>/pyproject.toml만 일치합니다. 재귀적 포함에는 /**를 사용합니다: src/**.

제외는 고정되지 않습니다(unanchored). __pycache__는 일치하는 모든 디렉터리를 제외합니다. / 접두사로 고정합니다: /dist는 <root>/dist만 제외합니다.

모든 패턴은 백슬래시 이스케이프 지원과 함께 PEP 639의 축소된 이식 가능 글로브 구문을 사용합니다.

원문(영어): https://docs.astral.sh/uv/concepts/build-backend/ · 본 문서는 학습용 한국어 번역이며 원본의 권리는 원저작자(Astral)에게 있습니다.

원문(영어): https://docs.astral.sh/uv/concepts/build-backend/