11.. _porting :
22
3- =========================
3+ ============================
4+ Porting and platform support
5+ ============================
6+
7+ The Python interpreter runs on an underlying *platform * -- the operating system
8+ (for example, Linux, Windows or macOS), processor (like Intel/AMD, ARM),
9+ C compiler and library, and other "lower level" details.
10+
11+ CPython is *officially supported * on several platforms, on which the core team
12+ has adequate knowledge and resources to test releases and fix bugs.
13+ See :pep: `11 ` for details.
14+
15+ Other platforms are unsupported *by the core team *, but might be supported
16+ by others -- as a volunteer project, by a company that wants Python on "their"
17+ system, or just as a one-off experiment.
18+ See :pep: `PEP 11 <11#unsupported-platforms >` for the policy on merging code for
19+ unsupported platforms into the main CPython repository.
20+
21+
22+ .. _ports :
23+
24+ Ports and contacts
25+ ==================
26+
27+ The table below lists relevant third-party projects,
28+ their maintainers, and links to information that's relevant when triaging
29+ platform-specific issues.
30+ Officially supported platforms are also included when there is relevant
31+ information for them (beyond :pep: `11 `), or to group similar platforms.
32+
33+ It is OK to @mention the listed GitHub usernames to draw maintainers' attention
34+ or request their opinion on platform-specific issues.
35+ Maintainers must only be listed with their permission, and they may remove
36+ themselves at any time.
37+
38+ Third-party projects should only be listed if they benefit substantially
39+ more people than the maintainers.
40+
41+ Links should be for the port specifically (not the platform itself),
42+ and relevant for porting work and fixing platform-specific issues
43+ (no homepage/marketing links).
44+
45+ .. list-table ::
46+ :header-rows: 1
47+
48+ * - Platform
49+ - Maintainers
50+ - Information
51+ * - **AIX **
52+ - :github-user: `ayappanec `
53+ -
54+ * - **Android ** [t3 ]_
55+ - :github-user: `mhsmith `
56+ - `Usage <https://docs.python.org/3/using/android.html >`__,
57+ `Limitations <https://docs.python.org/3/library/intro.html#mobile-platforms >`__,
58+ :cpy-file: `Platforms/Android `
59+ * - **iOS ** [t3 ]_
60+ - :github-user: `freakboy3742 `, :github-user: `ned-deily `
61+ - `Usage <https://docs.python.org/3/using/ios.html >`__,
62+ `Limitations <https://docs.python.org/3/library/intro.html#mobile-platforms >`__,
63+ :cpy-file: `Platforms/Apple `
64+ * - **Linux ** [t1 ]_
65+ -
66+ -
67+ * - \- Fedora
68+ - :github-user: `hroncok `, :github-user: `befeleme `
69+ - `Config & patches <https://src.fedoraproject.org/rpms/python3.15/tree/rawhide >`_,
70+ `Bugs <https://bugzilla.redhat.com/buglist.cgi?bug_status=__open__&classification=Fedora&columnlist=product%2Ccomponent%2Cassigned_to%2Cbug_status%2Cshort_desc%2Cchangeddate%2Cbug_severity&f1=component&o1=regexp&order=status%2C%20assigned_to%2C%20id%2C%20&product=Fedora&product=Fedora%20EPEL&query_format=advanced&v1=python3%5C.%5Cd%2B%24 >`__,
71+ `Maintenance guide <https://hackmd.io/9f64YNIZTCy0ZzKb5wKtqQ?view >`__
72+ * - \- Debian
73+ - :github-user: `stefanor `
74+ - `Config & patches <https://salsa.debian.org/cpython-team/python3/-/tree/master/debian >`_,
75+ `Bugs <https://bugs.debian.org/cgi-bin/pkgreport.cgi?src=python3.15 >`__,
76+ `Wiki <https://wiki.debian.org/Python >`__
77+ * - \- Ubuntu
78+ - :github-user: `stefanor `
79+ - `Config & patches <https://git.launchpad.net/ubuntu/+source/python3.15/tree/debian >`_ (by version),
80+ `Bugs <https://launchpad.net/ubuntu/+source/python3-defaults/+bugs >`__
81+ * - \- Alpine
82+ -
83+ - `Config & patches <https://github.com/alpinelinux/aports/tree/master/main/python3 >`_
84+ * - **macOS ** [t1 ]_
85+ - :gh-python-team: `macos-team `, :github-user: `freakboy3742 `
86+ - `Usage <https://docs.python.org/3/using/mac.html >`__,
87+ :cpy-file: `Platforms/Apple `
88+ * - **Solaris **/OpenIndiana
89+ - :github-user: `jcea `, :github-user: `kulikjak `
90+ -
91+ * - **WebAssembly **
92+ -
93+ - `Limitations <https://docs.python.org/3/library/intro.html#webassembly-platforms >`__
94+ * - \- WASI [t2 ]_
95+ -
96+ - :cpy-file: `WASI <Platforms/WASI> `
97+ * - \- Emscripten [t3 ]_
98+ - :github-user: `pmp-p `, :github-user: `rdb `, :github-user: `hoodmane `
99+ - :cpy-file: `emscripten <Platforms/emscripten> `
100+ * - \- Pyodide
101+ - :github-user: `ryanking13 `, :github-user: `agriyakhetarpal `
102+ -
103+ * - **Windows ** [t1 ]_
104+ - :gh-python-team: `windows-team `, :github-user: `pfmoore `
105+ - `Usage <https://docs.python.org/3/using/windows.html >`__,
106+ :cpy-file: `PC `,
107+ :cpy-file: `PCbuild `
108+ * - **Cross-Platform **
109+ -
110+ -
111+ * - \- conda-forge
112+ -
113+ - `Recipe <https://github.com/conda-forge/python-feedstock/tree/main/recipe >`_
114+
115+ .. [t1 ] Specific variants have official :pep: `Tier 1 support <11#tier-1 >`
116+ t2 ] Specific variants have official :pep: `Tier 2 support <11#tier-2 >`
117+ t3 ] Specific variants have official :pep: `Tier 3 support <11#tier-3 >`
118+
119+
4120
5121=========================
6122
123+ Porting CPython to an entirely new platform is an adventure.
124+ If you try it, consider keeping notes -- and updating this guide, if you
125+ find something that might be relevant to others.
126+ Since each platform is different, this guide can only give you a
127+ few rough tips.
128+
7129The first step is to familiarize yourself with the development toolchain on
8130the platform in question, notably the C compiler. Make sure you can compile and
9131run a hello-world program using the target compiler.
@@ -12,23 +134,39 @@ Next, learn how to compile and run the Python interpreter on a platform to
12134which it has already been ported; preferably Unix, but Windows will
13135do, too. The build process for Python, in particular the ``Makefile `` in the
14136source distribution, will give you a hint on which files to compile
15- for Python. Not all source files are relevant: some are platform-specific,
16- and others are only used in emergencies (for example, ``getopt.c ``).
137+ for Python. Not all source files are relevant: some are platform-specific,
138+ and others are only used in emergencies (for example,
139+ :cpy-file: `Python/getopt.c `).
17140
18141It is not recommended to start porting Python without at least a medium-level
19142understanding of your target platform; how it is generally used, how to
20143write platform-specific apps, and so on. Also, some Python knowledge is required, or
21144you will be unable to verify that your port is working correctly.
22145
23- You will need a ``pyconfig.h `` file tailored for your platform. You can
24- start with ``pyconfig.h.in ``, read the comments, and turn on definitions that
25- apply to your platform. Also, you will need a ``config.c `` file, which lists
26- the built-in modules you support. Again, starting with
27- ``Modules/config.c.in `` is recommended.
146+ On systems with a UNIX shell, run the included :cpy-file: `configure ` script.
147+ This should generate all required files, including a :file: `Makefile `.
148+ If it does not, you will need to debug it (or reimplement it).
149+ Note that the script is generated from :cpy-file: `configure.ac ` using GNU
150+ Autotools.
151+ (CPython pins a specific version for reproducibility, but other versions may
152+ work fine.)
153+
154+ The main files that ``configure `` generates -- and which you might want to
155+ check -- are:
28156
29- Finally, you will run into some things that are not supported on your
30- target platform. Forget about the ``posix `` module in the beginning. You can
31- simply comment it out of the ``config.c `` file.
157+ * A :file: `pyconfig.h ` file tailored for your platform.
158+ If you need to create this manually, start with :cpy-file: `pyconfig.h.in `,
159+ read the comments, and turn on definitions that apply to your platform.
160+ * A :file: `config.c ` file, which lists the built-in modules you support.
161+ Until you get dynamic extension loading to work, all compiled modules
162+ you need to import will need to be listed here.
163+ The file is generated from :cpy-file: `Modules/config.c.in `.
164+ * A :file: `Makefile ` with instructions to put everything together.
165+ If one isn't generated, try compiling all the ``*.c `` files, and fix the
166+ errors -- or omit files that don't look important.
167+ For example, forget about the ``posix `` module
168+ (:cpy-file: `Modules/posixmodule.c `) in the beginning: don't compile it,
169+ and comment it out of the :file: `config.c ` file.
32170
33171Keep working on it until you get a ``>>> `` prompt. You may have to disable the
34172importing of ``site.py `` by passing the ``-S `` option. When you have a prompt,
@@ -38,6 +176,9 @@ At some point you will want to use the ``os`` module; this is the time to start
38176thinking about what to do with the ``posix `` module. It is okay to simply
39177comment out functions in the ``posix `` module that cause problems; the
40178remaining ones will be quite useful.
179+ You can use the same approach for other modules too, of course.
41180
42181Before you are done, it is highly recommended to run the Python regression test
43182suite, as described in :ref: `runtests `.
183+ You will probably need to skip tests that do not make sense; for inspiration
184+ look at how that's done for the WASI platform.
0 commit comments