diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index e1a53a4982..7a2cf702a0 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -5,6 +5,14 @@ Setup and building ================== +.. raw:: html + + + .. highlight:: console These instructions cover how to get a working copy of the source code and a @@ -257,7 +265,6 @@ to learn more about these options. $ ./configure --enable-optimizations --with-lto - .. _windows-compiling: Windows @@ -339,156 +346,155 @@ and how to build. .. _build-dependencies: +.. _deps-on-linux: +.. _macOS and OS X: +.. _macOS: Install dependencies ==================== This section explains how to install additional extensions (e.g. ``zlib``) -on :ref:`Linux ` and :ref:`macOS`. On Windows, -extensions are already included and built automatically. +on :ref:`Linux ` and :ref:`macOS`. -.. _deps-on-linux: +.. tab:: Linux -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. -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**, **Red Hat Enterprise Linux** and other ``yum`` based systems:: -On **Fedora**, **Red Hat Enterprise Linux** and other ``yum`` based systems:: + $ sudo yum install yum-utils + $ sudo yum-builddep python3 - $ sudo yum install yum-utils - $ sudo yum-builddep python3 + On **Fedora** and other ``DNF`` based systems:: -On **Fedora** and other ``DNF`` based systems:: + $ sudo dnf install dnf-plugins-core # install this to use 'dnf builddep' + $ sudo dnf builddep python3 - $ 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. -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:: -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 - deb-src http://archive.ubuntu.com/ubuntu/ jammy main + Alternatively, uncomment lines with ``deb-src`` using an editor, e.g.:: -Alternatively, uncomment lines with ``deb-src`` using an editor, e.g.:: + sudo nano /etc/apt/sources.list - sudo nano /etc/apt/sources.list + For other distributions, like Debian, change the URL and names to correspond + with the specific distribution. -For other distributions, like Debian, change the URL and names to correspond -with the specific distribution. + Then you should update the packages index:: -Then you should update the packages index:: + $ sudo apt-get update - $ sudo apt-get update + Now you can install the build dependencies via ``apt``:: -Now you can install the build dependencies via ``apt``:: + $ sudo apt-get build-dep python3 + $ sudo apt-get install pkg-config - $ 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:: -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 - $ 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 +.. tab:: macOS -.. _macOS and OS X: -.. _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. -macOS ------ + If necessary, run the following:: -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. + $ xcode-select --install -If necessary, run the following:: + This will also ensure that the system header files are installed into + ``/usr/include``. - $ xcode-select --install + .. _Homebrew: https://brew.sh -This will also ensure that the system header files are installed into -``/usr/include``. + .. _MacPorts: https://www.macports.org -.. _Homebrew: https://brew.sh + 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. -.. _MacPorts: https://www.macports.org + For example, with **Homebrew**, install the dependencies:: -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. + $ brew install pkg-config openssl@3.0 xz gdbm tcl-tk -For example, with **Homebrew**, install the dependencies:: + Then, for Python 3.11 and newer, run ``configure``:: - $ brew install pkg-config openssl@3.0 xz gdbm tcl-tk + $ 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)" -Then, for Python 3.11 and newer, run ``configure``:: + Or, for Python 3.8 through 3.10:: - $ 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)" + $ 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)" -Or, for Python 3.8 through 3.10:: + And finally, run ``make``:: - $ 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)" + $ make -s -j2 -And finally, run ``make``:: + Alternatively, with **MacPorts**:: - $ make -s -j2 + $ sudo port install pkgconfig openssl xz gdbm tcl tk +quartz -Alternatively, with **MacPorts**:: + Then, for Python 3.11 and newer, run ``configure``:: - $ sudo port install pkgconfig openssl xz gdbm tcl tk +quartz + $ GDBM_CFLAGS="-I$(dirname $(dirname $(which port)))/include" \ + GDBM_LIBS="-L$(dirname $(dirname $(which port)))/lib -lgdbm" \ + ./configure --with-pydebug -Then, for Python 3.11 and newer, run ``configure``:: + And finally, run ``make``:: - $ GDBM_CFLAGS="-I$(dirname $(dirname $(which port)))/include" \ - GDBM_LIBS="-L$(dirname $(dirname $(which port)))/lib -lgdbm" \ - ./configure --with-pydebug + $ make -s -j2 -And finally, run ``make``:: + 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`. - $ make -s -j2 + Explaining how to build optional dependencies on a Unix-based system without + root access is beyond the scope of this guide. -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`. + For more details on various options and considerations for building, refer + to the `macOS README + `_. -Explaining how to build optional dependencies on a Unix-based system without -root access is beyond the scope of this guide. + .. _clang: https://clang.llvm.org/ + .. _ccache: https://ccache.dev/ -For more details on various options and considerations for building, refer -to the `macOS README -`_. + .. 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. -.. _clang: https://clang.llvm.org/ -.. _ccache: https://ccache.dev/ +.. tab:: Windows -.. 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. + On Windows, extensions are already included and built automatically. .. _regenerate_configure: