Skip to content

Commit

Permalink
Add inline tabs on Setup and Building page for commands on different …
Browse files Browse the repository at this point in the history 
…systems (#1226)
  • Loading branch information
@lancegoyke
lancegoyke committed Nov 23, 2023
1 parent 1909f67 commit 6d96e57
Showing 1 changed file with 104 additions and 98 deletions.
202 changes: 104 additions & 98 deletions getting-started/setup-building.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,14 @@
Setup and building
==================

.. raw:: html

<script>
document.addEventListener('DOMContentLoaded', function() {
activateTab(getOS());
});
</script>

.. highlight:: console

These instructions cover how to get a working copy of the source code and a
Expand Down Expand Up @@ -257,7 +265,6 @@ to learn more about these options.
$ ./configure --enable-optimizations --with-lto
.. _windows-compiling:

Windows
Expand Down Expand Up @@ -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 <deps-on-linux>` and :ref:`macOS`. On Windows,
extensions are already included and built automatically.
on :ref:`Linux <deps-on-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
<https://github.com/python/cpython/blob/main/Mac/README.rst>`_.

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
<https://github.com/python/cpython/blob/main/Mac/README.rst>`_.
.. 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:
Expand Down

0 comments on commit 6d96e57

Please sign in to comment.