From 34bf66982a1bddb5ef73995ca5b597fab266686b Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Wed, 17 Jun 2026 14:05:38 +0200 Subject: [PATCH] Update Porting page, move platform experts list there Rename page to "Porting and Platform support". Move the "Platforms" list from the Experts Index here. Add relevant links (setup guides, issue trackers, config/patches). Update the guide for porting to a new platform a bit. --- conf.py | 1 + core-team/experts.rst | 18 +---- developer-workflow/porting.rst | 139 ++++++++++++++++++++++++++++++--- 3 files changed, 131 insertions(+), 27 deletions(-) diff --git a/conf.py b/conf.py index 020e6bf6af..e071e1328d 100644 --- a/conf.py +++ b/conf.py @@ -276,6 +276,7 @@ "gh-label": (f"{_repo}/labels/%s", "%s"), "github": ("https://github.com/%s", "%s"), "github-user": ("https://github.com/%s", "@%s"), + "gh-python-team": ("https://github.com/orgs/python/teams/%s", "@%s"), "pypi": ("https://pypi.org/project/%s/", "%s"), "pypi-org": ("https://pypi.org/org/%s/", "%s"), } diff --git a/core-team/experts.rst b/core-team/experts.rst index a5fd9c9358..8152cb09e2 100644 --- a/core-team/experts.rst +++ b/core-team/experts.rst @@ -179,23 +179,9 @@ PEG Generator gvanrossum, pablogsal, lysnikolaou Platforms ========= -For official contacts for supported platforms, see :pep:`11`. +The **Platforms experts list** has moved to :ref:`ports`. -Platforms listed here are not necessarily supported by CPython. -Some of the experts listed here maintain and distribute Python -for “their” platform as a third-party project. - -=================== =========== -Platform Maintainers -=================== =========== -AIX ayappanec -Android mhsmith -Emscripten hoodmane, pmp-p, rdb, rth, ryanking13 -iOS freakboy3742, ned-deily -macOS ronaldoussoren, ned-deily, freakboy3742 -Solaris/OpenIndiana jcea, kulikjak -Windows tjguk, zooba, pfmoore -=================== =========== +For official contacts for supported platforms, see :pep:`11`. Miscellaneous diff --git a/developer-workflow/porting.rst b/developer-workflow/porting.rst index f308e6c14b..aeeed70e2f 100644 --- a/developer-workflow/porting.rst +++ b/developer-workflow/porting.rst @@ -1,9 +1,107 @@ .. _porting: -========================= +============================ +Porting and platform support +============================ + +The Python interpreter runs on an underlying *platform* -- the operating system +(for example, Linux, Windows or macOS), processor (like Intel/AMD, ARM), +C compiler and library, and other "lower level" details. + +CPython is *officially supported* on several platforms, on which the core team +has adequate knowledge and resources to test releases and fix bugs. +See :pep:`11` for details. + +Other platforms are unsupported *by the core team*, but might be supported +by others -- as a volunteer project, by a company that wants Python on "their" +system, or just as a one-off experiment. +See :pep:`11#unsupported-platforms` for the policy on merging code for +unsupported platforms into the main CPython repository. + + +.. _ports: + +Ports and contacts +================== + +The table below lists relevant third-party projects, +their maintainers, and links to information that's relevant when triaging +platform-specific issues. + +It is OK to @mention the listed GitHub usernames to draw maintainers' attention +or request their opinion on platform-specific issues. +Maintainers must only be listed with their permission, and they may remove +themselves at any time. + +Third-party projects should only be listed if they benefit substantially +more people than the maintainer(s). +Officially supported platforms are included when there are relevant links +to show, or to group similar platforms. + +Links should be for the port specifically (not the platform itself), +and relevant for porting work and fixing platform-specific issues +(no homepage/marketing links). + +* **AIX**: :github-user:`ayappanec` +* **Linux** [t1]_ + + * Fedora: :github-user:`hroncok`, :github-user:`befeleme`; see + `Config & patches `_, + `Bugs `__, + `Maintenance guide `__ + * Debian: :github-user:`stefanor`, :github-user:`doko42`; see + `Config & patches `_, + `Bugs `__, + `Wiki `__ + * Alpine: see + `Config & patches `_ +* **macOS** [t1]_: :gh-python-team:`macos-team`, :github-user:`freakboy3742`; + see + `Limitations `__, + `Usage `__, + :cpy-file:`Platforms/Apple` +* Mobile platforms: see + `Limitations `__ + + * **Android** [t3]_: :github-user:`mhsmith`; see + `Usage `__, + :cpy-file:`Platforms/Android` + * **iOS** [t3]_: :github-user:`freakboy3742`, :github-user:`ned-deily`; see + `Usage `__, + :cpy-file:`Platforms/Apple` + +* **Solaris**/OpenIndiana: :github-user:`jcea`, :github-user:`kulikjak` +* **WebAssembly**: see `Limitations `__ + + * WASI [t2]_: see :cpy-file:`WASI ` + * Emscripten [t3]_: :github-user:`pmp-p`, :github-user:`rdb`, :github-user:`rth`; see + :cpy-file:`emscripten ` + + * Pyodide: :github-user:`hoodmane`, :github-user:`ryanking13`, :github-user:`agriyakhetarpal` + +* **Windows** [t1]_: :gh-python-team:`windows-team`, :github-user:`pfmoore`; see + `Usage `__, + :cpy-file:`PC`, + :cpy-file:`PCbuild` +* **Cross-Platform**: + + * conda-forge: see + `Recipe `_ + +.. [t1] Specific variants have official :pep:`Tier 1 support <11#tier-1>` +.. [t2] Specific variants have official :pep:`Tier 2 support <11#tier-2>` +.. [t3] Specific variants have official :pep:`Tier 3 support <11#tier-3>` + + Porting to a new platform ========================= +Porting CPython to an entirely new platform is an adventure. +If you try it, consider keeping notes -- and updating this guide, if you +find something that might be relevant to others. +Since each platform is different, this guide can only give you a +few rough tips. + The first step is to familiarize yourself with the development toolchain on the platform in question, notably the C compiler. Make sure you can compile and run a hello-world program using the target compiler. @@ -12,23 +110,39 @@ Next, learn how to compile and run the Python interpreter on a platform to which it has already been ported; preferably Unix, but Windows will do, too. The build process for Python, in particular the ``Makefile`` in the source distribution, will give you a hint on which files to compile -for Python. Not all source files are relevant: some are platform-specific, -and others are only used in emergencies (for example, ``getopt.c``). +for Python. Not all source files are relevant: some are platform-specific, +and others are only used in emergencies (for example, +:cpy-file:`Python/getopt.c`). It is not recommended to start porting Python without at least a medium-level understanding of your target platform; how it is generally used, how to write platform-specific apps, and so on. Also, some Python knowledge is required, or you will be unable to verify that your port is working correctly. -You will need a ``pyconfig.h`` file tailored for your platform. You can -start with ``pyconfig.h.in``, read the comments, and turn on definitions that -apply to your platform. Also, you will need a ``config.c`` file, which lists -the built-in modules you support. Again, starting with -``Modules/config.c.in`` is recommended. +On systems with a UNIX shell, run the included :cpy-file:`configure` script. +This should generate all required files, including a :file:`Makefile`. +If it does not, you will need to debug it (or reimplement it). +Note that the script is generated from :cpy-file:`configure.ac` using GNU +Autotools. +(CPython pins a specific version for reproducibility, but other versions may +work fine.) + +The main files that ``configure`` generates -- and which you might want to +check -- are: -Finally, you will run into some things that are not supported on your -target platform. Forget about the ``posix`` module in the beginning. You can -simply comment it out of the ``config.c`` file. +* A :file:`pyconfig.h` file tailored for your platform. + If you need to create this manually, start with :cpy-file:`pyconfig.h.in`, + read the comments, and turn on definitions that apply to your platform. +* A :file:`config.c` file, which lists the built-in modules you support. + Until you get dynamic extension loading to work, all compiled modules + you need to import will need to be listed here. + The file is generated from :cpy-file:`Modules/config.c.in`. +* A :file:`Makefile` with instructions to put everything together. + If one isn't generated, try compiling all the ``*.c`` files, and fix the + errors -- or omit files that don't look important. + For example, forget about the ``posix`` module + (:cpy-file:`Modules/posixmodule.c`) in the beginning: don't compile it, + and comment it out of the :file:`config.c` file. Keep working on it until you get a ``>>>`` prompt. You may have to disable the importing of ``site.py`` by passing the ``-S`` option. When you have a prompt, @@ -38,6 +152,9 @@ At some point you will want to use the ``os`` module; this is the time to start thinking about what to do with the ``posix`` module. It is okay to simply comment out functions in the ``posix`` module that cause problems; the remaining ones will be quite useful. +You can use the same approach for other modules too, of course. Before you are done, it is highly recommended to run the Python regression test suite, as described in :ref:`runtests`. +You will probably need to skip tests that do not make sense; for inspiration +look at how that's done for the WASI platform.