From c66e9b1bdbfe14152748ade7c17b13266bab4a0d Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Wed, 18 Jun 2025 14:28:21 -0700 Subject: [PATCH 1/8] Add instructions on how to use the dev container image from GHCR Along the way make using the container outside of GitHub Codespaces its own section. --- getting-started/setup-building.rst | 63 +++++++++++++++++++++++------- 1 file changed, 49 insertions(+), 14 deletions(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 62da6b3fb..55945e4b2 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -1188,19 +1188,57 @@ select the option ``Open in VS Code``. You will still be working on the remote codespace instance, thus using the remote instance's compute power. The compute power may be a much higher spec than your local machine which can be helpful. +.. c_codespaces_end + +.. _devcontainer-directly: -Building the container locally ------------------------------- +Using the dev container directly +================================ If you want more control over the environment, or to work offline, -you can build the container locally. +you can use the same container used in +:ref:`GitHub Codespaces ` directly. This is meant for users who have (or want to get) some experience with containers. -The following instructions are a starting point for -your own customizations. -They assume a Unix-like environment, and Docker or Podman installed. +These instructions assume a Unix-like environment with +`Docker `__ or `Podman `__ +installed. + +.. _devcontainer-image: + +Using the pre-built container image +----------------------------------- + +`Dev container images `__ +are available from the +`GitHub Container Registry (GHCR) account for the Python org `__ . + +You can download the latest version of the container image via: + +.. code-block:: bash + + docker pull ghcr.io/python/devcontainer:latest + +(Substitute ``podman`` for ``docker`` if you use Podman.) -In a clone of the `cpython-devcontainers repo `_, +To run the container and launch a Bash shell, run one of the following commands +in a clone of the CPython repository. + +.. code-block:: bash + + docker run -it --rm --volume $PWD:/workspace --workdir /workspace ghcr.io/python/devcontainer:latest + +.. code-block:: bash + + podman run -it --rm --volume $PWD:/workspace:Z --workdir /workspace ghcr.io/python/devcontainer:latest + +.. _devcontainer-build: + +Building yourself +----------------- + +If you prefer, you can build the container image yourself. In a clone of the +`cpython-devcontainers repo `_, build the container and name it ``cpython-dev``: .. code-block:: bash @@ -1213,8 +1251,8 @@ The same command will update any existing ``cpython-dev`` container. Run it again from time to time -- especially if the container stops working for you. -To run the container, run one of the following commands in a clone of the -CPython repository. +To run the container and launch a Bash shell, run one of the following commands +in a clone of the CPython repository. .. code-block:: bash @@ -1224,11 +1262,8 @@ CPython repository. podman run -it --rm --volume $PWD:/workspace:Z --workdir /workspace cpython-dev -Note that the container has read/write access to the working directory. -You may want to use a separate clone of CPython, or run ``make clean`` -to remove caches and build output generated for your host OS. - -.. c_codespaces_end +The same caveats outlined above when running from a container image from GHCR +also apply here. From 7f75fab777b9a9ec7d7b9906c3986f82188df235 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Mon, 23 Jun 2025 12:01:49 -0700 Subject: [PATCH 2/8] Update getting-started/setup-building.rst Co-authored-by: Petr Viktorin --- getting-started/setup-building.rst | 8 -------- 1 file changed, 8 deletions(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 55945e4b2..cd4d95d87 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -1213,14 +1213,6 @@ Using the pre-built container image are available from the `GitHub Container Registry (GHCR) account for the Python org `__ . -You can download the latest version of the container image via: - -.. code-block:: bash - - docker pull ghcr.io/python/devcontainer:latest - -(Substitute ``podman`` for ``docker`` if you use Podman.) - To run the container and launch a Bash shell, run one of the following commands in a clone of the CPython repository. From 22485d67ce6c575aa9da8838e9ddfdd941139c07 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Tue, 24 Jun 2025 10:39:26 -0700 Subject: [PATCH 3/8] Apply suggestion from @hugovk Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- getting-started/setup-building.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index cd4d95d87..62441f77e 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -1188,8 +1188,6 @@ select the option ``Open in VS Code``. You will still be working on the remote codespace instance, thus using the remote instance's compute power. The compute power may be a much higher spec than your local machine which can be helpful. -.. c_codespaces_end - .. _devcontainer-directly: Using the dev container directly From 7792f9b378177c22cd0e7f93b2f623e5a951dc4b Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Tue, 24 Jun 2025 10:39:53 -0700 Subject: [PATCH 4/8] Apply suggestion from @hugovk Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- getting-started/setup-building.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 62441f77e..1579a9d76 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -1209,7 +1209,7 @@ Using the pre-built container image `Dev container images `__ are available from the -`GitHub Container Registry (GHCR) account for the Python org `__ . +`GitHub Container Registry (GHCR) account for the Python org `__. To run the container and launch a Bash shell, run one of the following commands in a clone of the CPython repository. From 2442e01ac15000b693f9fae5c9847fc3c45f201b Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Tue, 24 Jun 2025 10:40:20 -0700 Subject: [PATCH 5/8] Apply suggestion from @encukou Co-authored-by: Petr Viktorin --- getting-started/setup-building.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 1579a9d76..6482c0ec9 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -1222,6 +1222,10 @@ in a clone of the CPython repository. podman run -it --rm --volume $PWD:/workspace:Z --workdir /workspace ghcr.io/python/devcontainer:latest +Note that the container has read/write access to the working directory. +You may want to use a separate clone of CPython, or run ``make clean`` +to remove caches and build output generated for your host OS. + .. _devcontainer-build: Building yourself From 49ebe576a5ac2833beab8c529b7d147ba97cc617 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Tue, 24 Jun 2025 10:40:27 -0700 Subject: [PATCH 6/8] Apply suggestion from @hugovk Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- getting-started/setup-building.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 6482c0ec9..c7e02ab65 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -1226,6 +1226,7 @@ Note that the container has read/write access to the working directory. You may want to use a separate clone of CPython, or run ``make clean`` to remove caches and build output generated for your host OS. +.. _building-the-container-locally .. _devcontainer-build: Building yourself From bcac3a603e6bee38785bfc416f2f226de5ed2633 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Tue, 24 Jun 2025 10:40:42 -0700 Subject: [PATCH 7/8] Apply suggestion from @hugovk Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- getting-started/setup-building.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index c7e02ab65..756845c68 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -1259,7 +1259,7 @@ in a clone of the CPython repository. The same caveats outlined above when running from a container image from GHCR also apply here. - +.. c_codespaces_end .. include:: ../links.rst From c71a628f275f6f43228a0a899abe60a48367b00f Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Thu, 26 Jun 2025 10:24:30 +0200 Subject: [PATCH 8/8] Add blank line --- getting-started/setup-building.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 756845c68..910808453 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -1259,6 +1259,7 @@ in a clone of the CPython repository. The same caveats outlined above when running from a container image from GHCR also apply here. + .. c_codespaces_end