diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index f653164d38..8e5c675533 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -143,6 +143,197 @@ To make sure your code is linted correctly, we recommend setting up Now pre-commit will run automatically on ``git commit``. +.. _build-dependencies: +.. _deps-on-linux: +.. _macOS and OS X: +.. _macOS: + +Install dependencies +==================== + +This section explains how to install additional extensions (e.g. ``zlib``) +on Linux, macOS and iOS. + +.. tab:: Linux + + For Unix-based systems, we try to use system libraries whenever available. + This means optional components will only build if the relevant system headers + are available. The best way to obtain the appropriate headers will vary by + distribution, but the appropriate commands for some popular distributions + are below. + + On **Fedora**, **RHEL**, **CentOS** and other ``dnf``-based systems:: + + $ sudo dnf install dnf-plugins-core # install this to use 'dnf builddep' + $ sudo dnf builddep python3 + + + On **Debian**, **Ubuntu**, and other ``apt``-based systems, try to get the + dependencies for the Python you're working on by using the ``apt`` command. + + First, make sure you have enabled the source packages in the sources list. + You can do this by adding the location of the source packages, including + URL, distribution name and component name, to ``/etc/apt/sources.list``. + Take Ubuntu 22.04 LTS (Jammy Jellyfish) for example:: + + $ deb-src http://archive.ubuntu.com/ubuntu/ jammy main + + Alternatively, uncomment lines with ``deb-src`` using an editor, e.g.:: + + $ sudo nano /etc/apt/sources.list + + For other distributions, like Debian, change the URL and names to correspond + with the specific distribution. + + Then you should update the packages index:: + + $ sudo apt-get update + + Now you can install the build dependencies via ``apt``:: + + $ sudo apt-get build-dep python3 + $ sudo apt-get install pkg-config + + If you want to build all optional modules, install the following packages and + their dependencies:: + + $ sudo apt-get install build-essential gdb lcov pkg-config \ + libbz2-dev libffi-dev libgdbm-dev libgdbm-compat-dev liblzma-dev \ + libncurses5-dev libreadline6-dev libsqlite3-dev libssl-dev \ + lzma lzma-dev tk-dev uuid-dev zlib1g-dev libmpdec-dev + + +.. tab:: macOS + + For **macOS systems** (versions 10.9+), + the Developer Tools can be downloaded and installed automatically; + you do not need to download the complete Xcode application. + + If necessary, run the following:: + + $ xcode-select --install + + This will also ensure that the system header files are installed into + ``/usr/include``. + + .. _Homebrew: https://brew.sh + + .. _MacPorts: https://www.macports.org + + Also note that macOS does not include several libraries used by the Python + standard library, including ``libzma``, so expect to see some extension module + build failures unless you install local copies of them. As of OS X 10.11, + Apple no longer provides header files for the deprecated system version of + OpenSSL which means that you will not be able to build the ``_ssl`` extension. + One solution is to install these libraries from a third-party package + manager, like Homebrew_ or MacPorts_, and then add the appropriate paths + for the header and library files to your ``configure`` command. + + .. tab:: Homebrew + + For **Homebrew**, install dependencies using ``brew``:: + + $ brew install pkg-config openssl@3.0 xz gdbm tcl-tk mpdecimal + + .. tab:: Python 3.13+ + + For Python 3.13 and newer:: + + $ GDBM_CFLAGS="-I$(brew --prefix gdbm)/include" \ + GDBM_LIBS="-L$(brew --prefix gdbm)/lib -lgdbm" \ + ./configure --with-pydebug \ + --with-system-libmpdec \ + --with-openssl="$(brew --prefix openssl@3.0)" + + .. tab:: Python 3.11-3.12 + + For Python 3.11 and 3.12:: + + $ GDBM_CFLAGS="-I$(brew --prefix gdbm)/include" \ + GDBM_LIBS="-L$(brew --prefix gdbm)/lib -lgdbm" \ + ./configure --with-pydebug \ + --with-openssl="$(brew --prefix openssl@3.0)" + + .. tab:: Python 3.8-3.10 + + For Python 3.8, 3.9, and 3.10:: + + $ CPPFLAGS="-I$(brew --prefix gdbm)/include -I$(brew --prefix xz)/include" \ + LDFLAGS="-L$(brew --prefix gdbm)/lib -L$(brew --prefix xz)/lib" \ + ./configure --with-pydebug \ + --with-openssl="$(brew --prefix openssl@3.0)" \ + --with-tcltk-libs="$(pkg-config --libs tcl tk)" \ + --with-tcltk-includes="$(pkg-config --cflags tcl tk)" + + .. tab:: MacPorts + + For **MacPorts**, install dependencies using ``port``:: + + $ sudo port install pkgconfig openssl xz gdbm tcl tk +quartz mpdecimal + + .. tab:: Python 3.13+ + + For Python 3.13 and newer:: + + $ GDBM_CFLAGS="-I$(dirname $(dirname $(which port)))/include" \ + GDBM_LIBS="-L$(dirname $(dirname $(which port)))/lib -lgdbm" \ + ./configure --with-pydebug \ + --with-system-libmpdec + + .. tab:: Python 3.11-3.12 + + For Python 3.11 and 3.12:: + + $ GDBM_CFLAGS="-I$(dirname $(dirname $(which port)))/include" \ + GDBM_LIBS="-L$(dirname $(dirname $(which port)))/lib -lgdbm" \ + ./configure --with-pydebug + + And finally, run ``make``:: + + $ make -s -j2 + + There will sometimes be optional modules added for a new release which + won't yet be identified in the OS-level build dependencies. In those cases, + just ask for assistance in the *Core Development* category on :ref:`help-discourse`. + + Explaining how to build optional dependencies on a Unix-based system without + root access is beyond the scope of this guide. + + For more details on various options and considerations for building, refer + to the `macOS README + `_. + + .. _clang: https://clang.llvm.org/ + .. _ccache: https://ccache.dev/ + + .. note:: While you need a C compiler to build CPython, you don't need any + knowledge of the C language to contribute! Vast areas of CPython are + written completely in Python: as of this writing, CPython contains slightly + more Python code than C. + +.. tab:: Windows + + On Windows, extensions are already included and built automatically. + +.. tab:: iOS + + As with CPython itself, the dependencies for CPython must be compiled for + each of the hardware architectures that iOS supports. Consult the + documentation for `XZ `__, `bzip2 + `__, `OpenSSL `__ and + `libffi `__ for details on how to configure + the project for cross-platform iOS builds. + + Alternatively, the `BeeWare Project `__ maintains a + `project for building iOS dependencies + `__, and distributes + `pre-compiled binaries + `__ for each + of the dependencies. If you use this project to build the dependencies + yourself, the subfolders of the ``install`` folder can be used to configure + CPython. If you use the pre-compiled binaries, you should unpack each tarball + into a separate folder, and use that folder as the configuration target. + .. _compiling: Compile and build @@ -176,7 +367,7 @@ additional requirements so that the compiled interpreter supports the desired features. If you want to install these optional dependencies, consult the -:ref:`build-dependencies` section below. +:ref:`build-dependencies` section above. If you don't need to install them, the basic steps for building Python for development is to configure it and then compile it. @@ -600,197 +791,6 @@ single test, or a subset of tests. See the `iOS README `__ for details. -.. _build-dependencies: -.. _deps-on-linux: -.. _macOS and OS X: -.. _macOS: - -Install dependencies -==================== - -This section explains how to install additional extensions (e.g. ``zlib``) -on Linux, macOS and iOS. - -.. tab:: Linux - - For Unix-based systems, we try to use system libraries whenever available. - This means optional components will only build if the relevant system headers - are available. The best way to obtain the appropriate headers will vary by - distribution, but the appropriate commands for some popular distributions - are below. - - On **Fedora**, **RHEL**, **CentOS** and other ``dnf``-based systems:: - - $ sudo dnf install dnf-plugins-core # install this to use 'dnf builddep' - $ sudo dnf builddep python3 - - - On **Debian**, **Ubuntu**, and other ``apt``-based systems, try to get the - dependencies for the Python you're working on by using the ``apt`` command. - - First, make sure you have enabled the source packages in the sources list. - You can do this by adding the location of the source packages, including - URL, distribution name and component name, to ``/etc/apt/sources.list``. - Take Ubuntu 22.04 LTS (Jammy Jellyfish) for example:: - - $ deb-src http://archive.ubuntu.com/ubuntu/ jammy main - - Alternatively, uncomment lines with ``deb-src`` using an editor, e.g.:: - - $ sudo nano /etc/apt/sources.list - - For other distributions, like Debian, change the URL and names to correspond - with the specific distribution. - - Then you should update the packages index:: - - $ sudo apt-get update - - Now you can install the build dependencies via ``apt``:: - - $ sudo apt-get build-dep python3 - $ sudo apt-get install pkg-config - - If you want to build all optional modules, install the following packages and - their dependencies:: - - $ sudo apt-get install build-essential gdb lcov pkg-config \ - libbz2-dev libffi-dev libgdbm-dev libgdbm-compat-dev liblzma-dev \ - libncurses5-dev libreadline6-dev libsqlite3-dev libssl-dev \ - lzma lzma-dev tk-dev uuid-dev zlib1g-dev libmpdec-dev - - -.. tab:: macOS - - For **macOS systems** (versions 10.9+), - the Developer Tools can be downloaded and installed automatically; - you do not need to download the complete Xcode application. - - If necessary, run the following:: - - $ xcode-select --install - - This will also ensure that the system header files are installed into - ``/usr/include``. - - .. _Homebrew: https://brew.sh - - .. _MacPorts: https://www.macports.org - - Also note that macOS does not include several libraries used by the Python - standard library, including ``libzma``, so expect to see some extension module - build failures unless you install local copies of them. As of OS X 10.11, - Apple no longer provides header files for the deprecated system version of - OpenSSL which means that you will not be able to build the ``_ssl`` extension. - One solution is to install these libraries from a third-party package - manager, like Homebrew_ or MacPorts_, and then add the appropriate paths - for the header and library files to your ``configure`` command. - - .. tab:: Homebrew - - For **Homebrew**, install dependencies using ``brew``:: - - $ brew install pkg-config openssl@3.0 xz gdbm tcl-tk mpdecimal - - .. tab:: Python 3.13+ - - For Python 3.13 and newer:: - - $ GDBM_CFLAGS="-I$(brew --prefix gdbm)/include" \ - GDBM_LIBS="-L$(brew --prefix gdbm)/lib -lgdbm" \ - ./configure --with-pydebug \ - --with-system-libmpdec \ - --with-openssl="$(brew --prefix openssl@3.0)" - - .. tab:: Python 3.11-3.12 - - For Python 3.11 and 3.12:: - - $ GDBM_CFLAGS="-I$(brew --prefix gdbm)/include" \ - GDBM_LIBS="-L$(brew --prefix gdbm)/lib -lgdbm" \ - ./configure --with-pydebug \ - --with-openssl="$(brew --prefix openssl@3.0)" - - .. tab:: Python 3.8-3.10 - - For Python 3.8, 3.9, and 3.10:: - - $ CPPFLAGS="-I$(brew --prefix gdbm)/include -I$(brew --prefix xz)/include" \ - LDFLAGS="-L$(brew --prefix gdbm)/lib -L$(brew --prefix xz)/lib" \ - ./configure --with-pydebug \ - --with-openssl="$(brew --prefix openssl@3.0)" \ - --with-tcltk-libs="$(pkg-config --libs tcl tk)" \ - --with-tcltk-includes="$(pkg-config --cflags tcl tk)" - - .. tab:: MacPorts - - For **MacPorts**, install dependencies using ``port``:: - - $ sudo port install pkgconfig openssl xz gdbm tcl tk +quartz mpdecimal - - .. tab:: Python 3.13+ - - For Python 3.13 and newer:: - - $ GDBM_CFLAGS="-I$(dirname $(dirname $(which port)))/include" \ - GDBM_LIBS="-L$(dirname $(dirname $(which port)))/lib -lgdbm" \ - ./configure --with-pydebug \ - --with-system-libmpdec - - .. tab:: Python 3.11-3.12 - - For Python 3.11 and 3.12:: - - $ GDBM_CFLAGS="-I$(dirname $(dirname $(which port)))/include" \ - GDBM_LIBS="-L$(dirname $(dirname $(which port)))/lib -lgdbm" \ - ./configure --with-pydebug - - And finally, run ``make``:: - - $ make -s -j2 - - There will sometimes be optional modules added for a new release which - won't yet be identified in the OS-level build dependencies. In those cases, - just ask for assistance in the *Core Development* category on :ref:`help-discourse`. - - Explaining how to build optional dependencies on a Unix-based system without - root access is beyond the scope of this guide. - - For more details on various options and considerations for building, refer - to the `macOS README - `_. - - .. _clang: https://clang.llvm.org/ - .. _ccache: https://ccache.dev/ - - .. note:: While you need a C compiler to build CPython, you don't need any - knowledge of the C language to contribute! Vast areas of CPython are - written completely in Python: as of this writing, CPython contains slightly - more Python code than C. - -.. tab:: Windows - - On Windows, extensions are already included and built automatically. - -.. tab:: iOS - - As with CPython itself, the dependencies for CPython must be compiled for - each of the hardware architectures that iOS supports. Consult the - documentation for `XZ `__, `bzip2 - `__, `OpenSSL `__ and - `libffi `__ for details on how to configure - the project for cross-platform iOS builds. - - Alternatively, the `BeeWare Project `__ maintains a - `project for building iOS dependencies - `__, and distributes - `pre-compiled binaries - `__ for each - of the dependencies. If you use this project to build the dependencies - yourself, the subfolders of the ``install`` folder can be used to configure - CPython. If you use the pre-compiled binaries, you should unpack each tarball - into a separate folder, and use that folder as the configuration target. - .. _regenerate_configure: Regenerate ``configure``