설정과 빌드¶

이 지침에서는 소스 코드의 작업 사본과 컴파일된 CPython 인터프리터를 얻는 방법을 설명합니다(CPython은 https://www.python.org/에서 받을 수 있는 버전의 Python입니다). 또한 CPython 소스 코드의 디렉터리 구조에 대한 개요도 제공합니다.

또는 Docker가 설치되어 있다면 공식 이미지를 사용할 수도 있습니다. 이 이미지에는 여러 Python 버전의 최신 릴리스와 Git head가 들어 있으며, 개발 및 테스트 용도로만 제공됩니다.

빠른 참조는 Git 설치부터 풀 리퀘스트 제출까지의 과정을 간략하게 요약합니다.

Git 설치¶

CPython은 버전 관리에 Git을 사용하여 개발됩니다. Git 명령줄 프로그램의 이름은 git이며, 이 이름은 Git 자체를 가리킬 때도 사용됩니다. Git은 일반적으로 쓰이는 모든 운영 체제에서 쉽게 설치할 수 있습니다.

설치

CPython 저장소는 GitHub에서 호스팅되므로, 단계별 설치 방법은 GitHub 설정 지침이나 Git 프로젝트 지침을 참조하십시오. TortoiseGit이나 GitHub Desktop 같은 그래픽 클라이언트를 고려해 볼 수도 있습니다.
구성

이름과 이메일을 구성하고 SSH 키를 만드십시오. 그러면 git pull, git push, git fetch 같은 명령을 실행할 때마다 사용자 이름과 비밀번호를 입력하지 않고도 GitHub와 상호 작용할 수 있습니다. Windows에서는 autocrlf도 활성화해야 합니다.

소스 코드 받기¶

CPython 저장소는 GitHub에서 호스팅됩니다. 소스 코드 사본을 얻으려면 GitHub에서 Python 저장소를 포크하고, 개인 포크의 로컬 클론을 만든 다음 원격 저장소를 구성해야 합니다.

이 단계는 컴퓨터마다 한 번만 실행하면 됩니다:

https://github.com/python/cpython으로 이동하십시오.
오른쪽 위의 Fork를 누르십시오.
저장소를 어디로 포크할지 물으면 자신의 사용자 이름으로 포크하도록 선택하십시오.
포크는 https://github.com/<username>/cpython에 만들어집니다.
GitHub 포크를 클론하십시오(<username>을 자신의 사용자 이름으로 바꾸십시오):
```
$ git clone git@github.com:<username>/cpython.git
```
(SSH 기반 URL과 HTTPS 기반 URL 모두 사용할 수 있습니다.)

upstream 원격 저장소를 추가한 다음, main은 upstream에서 풀하고 푸시는 항상 origin으로 하도록 git을 구성하십시오:

$ cd cpython
$ git remote add upstream https://github.com/python/cpython
$ git config --local branch.main.remote upstream
$ git remote set-url --push upstream git@github.com:<your-username>/cpython.git

설정이 올바른지 확인하십시오:

$ git remote -v
origin  git@github.com:<your-username>/cpython.git (fetch)
origin  git@github.com:<your-username>/cpython.git (push)
upstream        https://github.com/python/cpython (fetch)
upstream        git@github.com:<your-username>/cpython.git (push)
$ git config branch.main.remote
upstream

이 명령들에 대한 자세한 내용은 Git 부트캠프와 치트 시트를 참조하십시오.

모든 작업을 올바르게 했다면 이제 cpython 디렉터리에 코드 사본이 있고, 자신의 GitHub 포크(origin)와 공식 CPython 저장소(upstream)를 가리키는 두 개의 원격 저장소가 있어야 합니다.

이미 릴리스된 Python 버전, 즉 유지 보수 모드에 있는 버전의 작업 사본이 필요하다면 릴리스 브랜치를 체크아웃할 수 있습니다. 예를 들어 Python 3.13의 작업 사본을 체크아웃하려면 git switch 3.13을 실행하십시오.

이러한 업데이트를 할 때는 CPython을 다시 컴파일해야 합니다.

CPython은 자신이 작업 사본에서 실행되고 있다는 것을 인식한다는 점에 유의하십시오. 즉, 작업 사본에서 CPython의 소스 코드를 편집하면 Python 코드의 변경 사항이 인터프리터에 즉시 반영되어 바로 사용하고 테스트할 수 있습니다. (C 코드를 변경한 경우에는 아래에 설명된 대로 영향을 받는 파일을 다시 컴파일해야 합니다.)

문서 변경도 같은 저장소에서 할 수 있습니다. 시작하기을 참조하십시오.

커밋 전 검사를 위해 pre-commit을 Git 훅으로 설치¶

코드가 올바르게 린트되도록 pre-commit을 Git 훅으로 설정할 것을 권장합니다:

$ pre-commit install --allow-missing-config
pre-commit installed at .git/hooks/pre-commit

이제 git commit으로 커밋할 때 pre-commit이 자동으로 실행됩니다.

`configure` 재생성¶

Python에 POSIX 시스템 고유의 기능(예: 새로운 시스템 호출 사용)에 의존하는 변경을 가하는 경우, 해당 기능을 사용할 수 있는지 검사하도록 configure 스크립트를 갱신해야 합니다. Python의 configure 스크립트는 GNU Autoconf를 사용하여 configure.ac에서 생성됩니다.

configure.ac를 편집한 후에는 make regen-configure를 실행하여 configure, pyconfig.h.in, aclocal.m4를 생성하십시오. configure.ac를 변경한 풀 리퀘스트를 제출할 때는 생성된 파일의 변경 사항도 함께 커밋해야 합니다.

Python의 configure.ac 스크립트에는 특정 버전의 GNU Autoconf가 필요합니다. Python 3.12 이상에서는 GNU Autoconf v2.71이 필요합니다. Python 3.11 이하에서는 GNU Autoconf v2.69가 필요합니다.

configure를 재생성하는 권장 방법이자 단연 가장 쉬운 방법은 다음과 같습니다:

$ make regen-configure

이 방법은 Podman이나 Docker를 사용하여 적절한 버전의 GNU Autoconf로 재생성을 수행합니다.

make regen-configure를 사용할 수 없거나 사용하고 싶지 않다면 autoconf-archive와 pkg-config 유틸리티를 설치하고, pkg.m4 매크로 파일이 적절한 aclocal 위치에 있는지 확인하십시오:

$ ls $(aclocal --print-ac-dir) | grep pkg.m4

참고

autoreconf를 실행하는 것은 autoconf를 실행하는 것과 같지 않습니다. 예를 들어 autoconf만 단독으로 실행하면 pyconfig.h.in이 재생성되지 않습니다. autoreconf는 필요에 따라 autoconf와 여러 다른 도구를 반복해서 실행합니다.

ABI 덤프 재생성하기¶

유지 보수 브랜치(main 제외)에는 Doc/data/pythonX.Y.abi에 특수한 파일이 있으며, 이 파일을 통해 특정 풀 리퀘스트가 공개 ABI에 영향을 주는지 알 수 있습니다. 이 파일은 GitHub CI의 Check if the ABI has changed라는 검사에서 사용되며, 이 검사는 풀 리퀘스트에 ABI 변경 사항이 있는데 ABI 파일이 갱신되지 않은 경우 실패합니다.

이 검사는 안전장치 역할을 하며, 검사가 실패했다고 해서 반드시 풀 리퀘스트를 병합할 수 없다는 뜻은 아닙니다. 이 검사가 실패하면 관련 릴리스 관리자를 PR에 추가하여, 릴리스 관리자가 변경 사항을 인지하고 해당 변경이 가능한지 검증할 수 있도록 해야 합니다.

중요

ABI 변경은 첫 번째 릴리스 후보 이전까지 허용됩니다. 첫 번째 릴리스 후보 이후의 모든 릴리스는 네이티브 확장 및 Python 인터프리터와 상호 작용하는 기타 도구와의 호환성을 보장하기 위해 동일한 ABI를 유지해야 합니다. 릴리스 후보 단계에 관한 문서를 참조하십시오.

PR 검사가 실패하면 해당 실행에 갱신된 ABI 파일이 아티팩트로 첨부됩니다. 릴리스 관리자의 승인을 받은 후 이 파일을 내려받아 PR에 추가하면 검사를 통과할 수 있습니다.

regen abidump Make 타깃을 호출하여 ABI 파일을 직접 재생성할 수 있습니다. 이렇게 하려면 GitHub CI가 검사에 사용하는 것과 동일한 환경에서 ABI 파일을 재생성해야 한다는 점에 유의하십시오. 플랫폼마다 플랫폼별 세부 사항이 포함될 수 있어서, Python ABI가 같더라도 검사가 실패할 수 있기 때문입니다. CI와 같은 플랫폼을 사용하여 ABI 파일을 재생성하는 더 쉬운 방법은 Docker를 사용하는 것입니다:

# In the CPython root:
$ docker run -v$(pwd):/src:Z -w /src --rm -it ubuntu:22.04 \
    bash /src/.github/workflows/regen-abidump.sh

스크립트 실행에 사용하는 ubuntu 버전이 중요하며, CI가 ABI를 검사할 때 사용하는 버전과 반드시 일치해야 한다는 점에 유의하십시오. 자세한 내용은 .github/workflows/build.yml 파일을 참조하십시오.

빌드 문제 해결하기¶

이 섹션에서는 Python을 컴파일하는 동안 발생할 수 있는 일반적인 문제와 그 해결 방법을 제시합니다.

자동으로 생성된 파일을 다시 만들지 않기¶

경우에 따라 make를 실행하는 동안 Parser/asdl_c.py나 Python/makeopcodetargets.py 같은 스크립트에서 파이썬 오류가 발생할 수 있습니다. Python은 자체 코드의 일부를 자동으로 생성하므로, 처음부터 전체 빌드를 하려면 자동 생성 스크립트를 실행해야 합니다. 하지만 이 때문에 Python을 빌드하려면 이미 설치된 Python 인터프리터가 필요합니다. 또한 새 버전(3.x)의 Python이 설치된 상태에서 이전 버전(2.x)의 Python을 빌드하거나 그 반대의 경우에는 버전 불일치가 발생할 수도 있습니다.

이 문제를 해결하기 위해 자동 생성된 파일도 Git 저장소에 체크인됩니다. 따라서 자동 생성 스크립트를 건드리지 않는다면 실제로 무언가를 자동 생성할 필요는 없습니다.

편집기와 도구¶

Python은 매우 널리 사용되기 때문에 사실상 모든 코드 편집기가 어떤 형태로든 Python 코드 작성을 지원합니다. 다양한 코딩 도구도 Python을 지원합니다.

코어 개발자들이 Python으로 코딩하는 데 특별한 설명이 필요하다고 느낀 편집기와 도구는 추가 자료를 참조하십시오.

디렉터리 구조¶

CPython 소스 트리에는 여러 개의 최상위 디렉터리가 있습니다. 각 디렉터리에 무엇이 들어가도록 되어 있는지 알면 특정 기능이 어디에 구현되어 있는지 찾는 데 도움이 됩니다. 다만 모든 규칙에는 언제나 예외가 있다는 점을 알아 두십시오.

Doc: 공식 문서입니다. https://docs.python.org/ 에서 사용하는 것이 바로 이 문서입니다. 문서 빌드하기도 참조하십시오.
Grammar: Python의 PEG(Parser Expression Grammar) 문법 파일이 들어 있습니다.
Include: 인터프리터 전반에서 사용하는 모든 헤더 파일이 들어 있습니다.
Lib: 표준 라이브러리 중 순수 Python으로 구현된 부분입니다.
Mac: Mac 전용 코드입니다(예를 들어 IDLE을 macOS 애플리케이션으로 사용하기 위한 코드).
Misc: 다른 곳에 속하지 않는 것들입니다. 일반적으로 다양한 종류의 개발자용 문서입니다.
Modules: 표준 라이브러리 중 C로 구현된 부분(및 기타 일부 코드)입니다.
Objects: 모든 내장 타입의 코드입니다.
PC: Windows 전용 코드입니다.
PCbuild: python.org에서 제공하는 Windows 설치 프로그램에 현재 사용되는 MSVC 버전용 빌드 파일입니다.
Parser: 파서 관련 코드입니다. AST 노드의 정의도 여기에 있습니다.
Programs: CPython 인터프리터의 main 함수를 포함한 C 실행 파일의 소스 코드입니다.
Python: CPython 런타임의 핵심을 구성하는 코드입니다. 여기에는 컴파일러, 평가 루프(eval loop), 다양한 내장 모듈이 포함됩니다.
Tools: Python 유지 관리에 사용되는(또는 사용되었던) 다양한 도구입니다.

컨테이너 사용하기¶

컴퓨터에 추가 도구를 설치하지 않고 컨테이너를 사용하여 CPython을 빌드하는 방법은 여러 가지가 있습니다. 모든 방법은 어떤 식으로든 cpython-devcontainers repo에 정의된 컨테이너를 사용합니다.

GitHub Codespaces를 사용하여 기여하기¶

GitHub Codespaces란 무엇입니까?¶

로컬 개발 환경을 구성하지 않고 CPython에 기여를 시작하고 싶다면 GitHub Codespaces를 사용할 수 있습니다. Codespaces는 GitHub에서 제공하는 클라우드 기반 개발 환경으로, 개발자가 웹 브라우저나 Visual Studio Code(VS Code) 안에서 바로 코드를 작성, 빌드, 테스트, 디버그할 수 있게 해 줍니다.

시작을 돕기 위해 CPython에는 devcontainer 폴더가 있으며, 이 폴더에는 프로젝트의 모든 사용자에게 일관되고 버전 관리되는 codespace 구성을 제공하는 JSON 구성 파일이 들어 있습니다. 또한 이 폴더에는 Dockerfile도 들어 있어, 직접 사용하는 편을 선호한다면 같은 환경을 로컬의 Docker 컨테이너에 구성할 수 있습니다.

CPython codespace 만들기¶

다음은 Codespaces를 사용하여 풀 리퀘스트로 기여하는 데 필요한 기본 단계입니다. 먼저 GitHub에 호스팅된 CPython 저장소로 이동해야 합니다.

그런 다음 아래 단계를 따라야 합니다:

codespace 실행하기
- , 키를 눌러 현재 브랜치의 codespace 설정 화면을 여십시오
  - 기본 개발 컨테이너를 사용하려면(대부분 이것을 원할 것입니다) 녹색 Create new codespace 버튼을 클릭하십시오
  - 다른 컨테이너를 사용하려면 Change options를 클릭하고 알맞은 컨테이너를 선택하십시오
- 또는 녹색 Code 버튼을 클릭하고 codespaces 탭을 선택하십시오
  - 기본 개발 컨테이너를 사용하려면(대부분 이것을 원할 것입니다) 녹색 Create codespace on main 버튼을 클릭하십시오
  - 다른 컨테이너를 사용하려면 … 메뉴로 이동하여 New with options…를 선택하십시오
codespace를 설정하고 있음을 알리는 화면이 나타납니다. (참고: CPython devcontainer가 제공되므로 codespace는 거기에 지정된 구성을 사용합니다.)
VS Code 웹 버전이 웹 브라우저 안에서 열립니다. 이 웹 버전은 여러분의 코드와 이미 연결되어 있고, CPython과 그 문서가 이미 빌드된 원격 코드스페이스의 터미널에도 연결되어 있습니다.
준비가 되면 터미널에서 평소처럼 Git 명령을 사용하여 새 브랜치를 만들고, 변경 사항을 커밋하고 푸시하십시오!

저장소를 닫았다가 나중에 다시 돌아오더라도, CPython 저장소로 이동하여 codespaces 탭을 선택하고 가장 최근의 코드스페이스 세션을 선택하면 언제든지 코드스페이스를 재개할 수 있습니다. 그러면 중단했던 곳에서 이어서 작업할 수 있습니다!

로컬에서 Codespaces 사용하기¶

코드스페이스 화면의 왼쪽 아래에 Codespaces라고 적힌 초록색 또는 회색 사각형이 보입니다. 이것을 클릭하면 추가 옵션을 볼 수 있습니다. 로컬에 설치된 VS Code에서 작업하는 것을 선호한다면 Open in VS Code 옵션을 선택할 수 있습니다. 이 경우에도 여전히 원격 코드스페이스 인스턴스에서 작업하므로, 원격 인스턴스의 컴퓨팅 성능을 사용하게 됩니다. 이 컴퓨팅 성능은 로컬 컴퓨터보다 사양이 훨씬 높을 수 있으므로 도움이 될 수 있습니다.

개발 컨테이너 직접 사용하기¶

환경을 더 세밀하게 제어하고 싶거나 오프라인으로 작업하고 싶다면, GitHub Codespaces에서 사용하는 것과 같은 컨테이너를 직접 사용할 수 있습니다. 이 방법은 컨테이너를 다뤄 본 경험이 있는(또는 경험을 쌓고 싶은) 사용자를 위한 것입니다. 이 안내는 Docker 또는 Podman이 설치된 Unix 계열 환경을 전제로 합니다. 또한 이 안내는 기본 개발 컨테이너를 사용한다고 가정합니다. 다른 컨테이너(예: WASI 개발 컨테이너)를 사용하려면 명령을 적절히 수정하십시오.

미리 빌드된 컨테이너 이미지 사용하기¶

개발 컨테이너 이미지는 Python 조직의 GitHub Container Registry(GHCR) 계정에서 받을 수 있습니다.

컨테이너를 실행하고 Bash 셸을 시작하려면, CPython 저장소의 클론에서 다음 명령 중 하나를 실행하십시오.

Podman

podman run -it --rm --volume $PWD:/workspace:Z --workdir /workspace ghcr.io/python/devcontainer:latest

Docker

docker run -it --rm --volume $PWD:/workspace --workdir /workspace ghcr.io/python/devcontainer:latest

컨테이너에는 작업 디렉터리에 대한 읽기/쓰기 권한이 있다는 점에 유의하십시오. 별도의 CPython 클론을 사용하거나, make clean을 실행하여 호스트 OS용으로 생성된 캐시와 빌드 결과물을 제거하는 것이 좋습니다.

직접 빌드하기¶

원한다면 컨테이너 이미지를 직접 빌드할 수 있습니다. cpython-devcontainers repo의 클론에서 컨테이너를 빌드하고 이름을 cpython-dev로 지정하십시오:

Podman

podman build devcontainer/ --tag cpython-dev

Docker

docker build devcontainer/ --tag cpython-dev

기존 cpython-dev 컨테이너가 있으면 같은 명령으로 업데이트됩니다. 이 명령을 가끔씩 다시 실행하십시오. 특히 컨테이너가 제대로 작동하지 않을 때는 꼭 다시 실행하십시오.

컨테이너를 실행하고 Bash 셸을 시작하려면, CPython 저장소의 클론에서 다음 명령 중 하나를 실행하십시오.

Podman

podman run -it --rm --volume $PWD:/workspace:Z --workdir /workspace cpython-dev bash

Docker

docker run -it --rm --volume $PWD:/workspace --workdir /workspace cpython-dev bash

GHCR의 컨테이너 이미지로 실행할 때에 대해 위에서 설명한 주의 사항이 여기에도 똑같이 적용됩니다.

설정과 빌드¶

Git 설치¶

소스 코드 받기¶

커밋 전 검사를 위해 pre-commit을 Git 훅으로 설치¶

컴파일과 빌드¶

Unix¶

Clang¶

최적화¶

Windows¶

WASI¶

Emscripten¶

Android¶

iOS¶

의존성 설치¶

`configure` 재생성¶

ABI 덤프 재생성하기¶

빌드 문제 해결하기¶

자동으로 생성된 파일을 다시 만들지 않기¶

편집기와 도구¶

디렉터리 구조¶

컨테이너 사용하기¶

GitHub Codespaces를 사용하여 기여하기¶

GitHub Codespaces란 무엇입니까?¶

CPython codespace 만들기¶

로컬에서 Codespaces 사용하기¶

개발 컨테이너 직접 사용하기¶

미리 빌드된 컨테이너 이미지 사용하기¶

직접 빌드하기¶

설정과 빌드¶

Git 설치¶

소스 코드 받기¶

커밋 전 검사를 위해 pre-commit을 Git 훅으로 설치¶

컴파일과 빌드¶

Unix¶

Clang¶

최적화¶

Windows¶

WASI¶

Emscripten¶

Android¶

iOS¶

의존성 설치¶

configure 재생성¶

ABI 덤프 재생성하기¶

빌드 문제 해결하기¶

자동으로 생성된 파일을 다시 만들지 않기¶

편집기와 도구¶

디렉터리 구조¶

컨테이너 사용하기¶

GitHub Codespaces를 사용하여 기여하기¶

GitHub Codespaces란 무엇입니까?¶

CPython codespace 만들기¶

로컬에서 Codespaces 사용하기¶

개발 컨테이너 직접 사용하기¶

미리 빌드된 컨테이너 이미지 사용하기¶

직접 빌드하기¶

`configure` 재생성¶