diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index efa3cf31d..aa783f24e 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -1186,7 +1186,45 @@ 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. -.. TODO: add docker instructions + +Building the container locally +------------------------------ + +If you want more control over the environment, or to work offline, +you can build the container locally. +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. + +In a clone of the `cpython-devcontainers repo `_, +build the container and name it ``cpython-dev``: + +.. code-block:: bash + + docker build devcontainer/ --tag cpython-dev + +(Substitute ``podman`` for ``docker`` if you use Podman.) + +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. + +.. code-block:: bash + + docker run -it --rm --volume $PWD:/workspace --workdir /workspace cpython-dev + +.. code-block:: bash + + 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