설정 및 빌드¶

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

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

관련 빠른 참조는 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 원격 저장소를 추가한 다음, upstream에서 main 브랜치를 가져오고 항상 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` 재생성¶

새로운 시스템 호출을 사용하는 경우와 같이 일부 POSIX 시스템별 기능에 의존하는 변경 사항이 Python에 적용되면, 해당 기능의 사용 가능 여부를 검사하도록 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

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

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 파일을 검사할 때 사용하는 것과 동일한 환경에서 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 버전은 중요하며, ABI를 검사할 때 CI가 사용하는 버전과 반드시 일치해야 합니다. 자세한 내용은 .github/workflows/build.yml 파일을 참조하십시오.

빌드 문제 해결¶

이 절에서는 Python을 컴파일하는 동안 발생할 수 있는 몇 가지 일반적인 문제와 제안된 해결 방법을 나열합니다.

자동 생성 파일 다시 만들기 방지¶

일부 상황에서는 make를 실행하는 동안 Parser/asdl_c.py 또는 Python/makeopcodetargets.py 같은 스크립트에서 Python 오류가 발생할 수 있습니다. 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 루프 및 다양한 내장 모듈이 포함됩니다.
Tools: Python을 유지 관리하는 데 사용되거나 과거에 사용되었던 다양한 도구입니다.

컨테이너 사용하기¶

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

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

GitHub Codespaces란 무엇입니까?¶

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

시작하는 데 도움이 되도록 CPython에는 프로젝트의 모든 사용자에게 일관되고 버전이 지정된 codespace 구성을 제공하는 JSON 구성 파일이 포함된 devcontainer 폴더가 있습니다. 또한 동일한 환경을 로컬 Docker 컨테이너에 설정할 수 있는 Dockerfile도 포함되어 있으므로, 원하는 경우 이를 직접 사용할 수 있습니다.

CPython codespace 만들기¶

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

그런 다음 다음 단계를 수행해야 합니다.

codespace 시작하기
- 현재 브랜치의 codespace 설정 화면을 열려면 , 키를 누르십시오.
  - 기본 dev 컨테이너(대부분의 경우 원하는 옵션)의 경우 녹색 Create new codespace 버튼을 클릭하십시오.
  - 다른 컨테이너를 사용하려면 Change options를 클릭하고 적절한 컨테이너를 선택하십시오.
- 또는 녹색 Code 버튼을 클릭하고 codespaces 탭을 선택하십시오.
  - 기본 개발 컨테이너(대부분의 경우 원하는 옵션)를 사용하려면 초록색 Create codespace on main 버튼을 클릭하십시오.
  - 다른 컨테이너를 사용하려면 … 메뉴로 이동하여 New with options…를 선택하십시오.
코드스페이스를 설정하고 있음을 알리는 화면이 나타납니다. (참고: CPython 개발 컨테이너가 제공되므로 코드스페이스에서는 이 컨테이너가 지정한 구성을 사용합니다.)
VS Code 웹 버전이 웹 브라우저에서 열리며, 코드 및 CPython과 해당 문서가 이미 빌드된 원격 코드스페이스의 터미널에 연결되어 있습니다.
준비가 되면 터미널에서 일반적인 Git 명령을 사용하여 새 브랜치를 만들고 변경 사항을 커밋한 후 푸시하십시오!

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

로컬에서 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` 재생성¶