[pyproject.toml 완전 정복 2편] [build-system] 섹션 상세 파헤치기

pyproject.toml의 [build-system] 섹션은 PEP 518에서 정의한 표준으로, 프로젝트를 빌드할 때 필요한 빌드 백엔드와 빌드 단계 의존성을 명확히 지정하는 영역입니다. 이전에는 setup.py를 직접 실행하거나 명령어 옵션을 사용해 빌드 절차를 커스텀했지만, 이로 인해 일관성 없는 빌드 환경 및 복잡한 설정 문제가 있었습니다.

[build-system]을 활용하면 빌드 시 필요한 패키지(예: setuptools, wheel)와 빌드 백엔드(예: setuptools.build_meta, Poetry, Flit) 정보를 명료하게 선언하여, pip나 다른 설치 도구가 이를 자동 인식하고 재현성 높은 빌드 절차를 수행합니다.

기본 필드

[build-system] 섹션은 일반적으로 다음과 같은 필드를 갖습니다.

• requires: 빌드 백엔드와 빌드 시 필요한 의존성 패키지 목록 (리스트 형태)
• build-backend: 빌드 백엔드로 사용할 파이썬 모듈 경로(문자열)
• (선택사항) backend-path: 빌드 백엔드 소스를 로컬 디렉토리에서 가져올 때 사용(일반적 상황에서는 필요 없음)

예시:

[build-system]
requires = ["setuptools>=42", "wheel"]
build-backend = "setuptools.build_meta"

여기서는 setuptools와 wheel 패키지를 빌드 단계에 필요하다고 명시하고, 빌드 백엔드를 setuptools.build_meta로 지정하여, python -m build나 pip install 시 해당 정보를 자동으로 사용합니다.

빌드 백엔드 선택하기

빌드 백엔드는 패키지 빌드 방법을 정의하는 모듈입니다. 대표적인 예:

• setuptools.build_meta: 전통적인 setuptools 기반 빌드
• flit_core.buildapi: Flit 기반 간단한 빌드
• poetry.core.masonry.api: Poetry 기반 빌드

프로젝트 성격에 맞게 빌드 백엔드를 선택할 수 있습니다.

예: Flit 사용 시

[build-system]
requires = ["flit_core>=3.7,<4"]
build-backend = "flit_core.buildapi"

Flit은 단순 패키징에 강점이 있으며, pyproject.toml 정보만으로 손쉽게 wheel 빌드 가능.

빌드 백엔드별 특징

• setuptools.build_meta: 전통적 setuptools 에코시스템 활용, 호환성 광범위
• flit_core.buildapi: 설정 최소화, 심플한 패키지 빌드
• poetry.core.masonry.api: Poetry 기반 빌드로 고급 의존성 관리와 연계 가능
• hatchling: Hatch 빌드 백엔드, 최신 패키징 트렌드 반영

어떤 빌드 백엔드를 선택하느냐에 따라 [project] 섹션이나 [tool.*] 섹션 설정 패턴도 달라질 수 있습니다.

빌드 시 의존성 관리

requires 리스트에 명시된 패키지들은 빌드 시점에만 필요한 의존성입니다. pip는 이 리스트를 사용해 빌드 환경을 격리된 형태로 구성(pip install --no-build-isolation=False 시)하고, 이후 빌드 백엔드를 불러와 wheel 패키지 등을 생성합니다.

이렇게 하면 빌드 환경과 런타임 환경을 명확히 분리할 수 있으므로, 빌드 과정이 깨끗하고 예측 가능해집니다.

예: Poetry 빌드 백엔드 사용 시

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

여기서 poetry-core는 빌드 단계에서만 필요한 의존성. 실제 런타임 의존성은 [project] 섹션에 기록될 것입니다.

호환성 이슈 및 주의사항

• Python 버전 및 PEP 지원 여부: Python 3.6 이상이면 PEP 518을 지원하고, pip 최신 버전 사용 권장
• 빌드 백엔드별 문서 확인: setuptools, Flit, Poetry 등에 따라 [project] 섹션 설정 방식이 약간씩 다를 수 있으므로 해당 빌드 백엔드 공식 문서 참고

결론

• [build-system] 섹션은 빌드 백엔드와 빌드 시 필요한 의존성을 명확히 정의, 기존 setup.py 방식 대비 표준화와 재현성↑
• 빌드 백엔드 선택(세트업툴즈, 플릿, 포에트리 등)으로 프로젝트 성격에 맞는 빌드 프로세스 구성 가능
• 빌드 환경 자동화, 예측 가능한 패키징 흐름, CI/CD 파이프라인에서도 안정적인 빌드 환경 보장

다음 글에서는 [project] 섹션과 PEP 621 표준에 따른 패키지 메타데이터 정의 방법을 다루면서, setup.py 없이도 이름, 버전, 라이선스, 의존성 같은 정보 일원화하는 방법을 알아보겠습니다.