granicus.if.org Git - python/blob - README.rst

   1 This is Python version 3.9.0 alpha 0
   2 ====================================
   3
   4 .. image:: https://travis-ci.org/python/cpython.svg?branch=master
   5    :alt: CPython build status on Travis CI
   6    :target: https://travis-ci.org/python/cpython
   7
   8 .. image:: https://dev.azure.com/python/cpython/_apis/build/status/Azure%20Pipelines%20CI?branchName=master
   9    :alt: CPython build status on Azure DevOps
  10    :target: https://dev.azure.com/python/cpython/_build/latest?definitionId=4&branchName=master
  11
  12 .. image:: https://codecov.io/gh/python/cpython/branch/master/graph/badge.svg
  13    :alt: CPython code coverage on Codecov
  14    :target: https://codecov.io/gh/python/cpython
  15
  16 .. image:: https://img.shields.io/badge/zulip-join_chat-brightgreen.svg
  17    :alt: Python Zulip chat
  18    :target: https://python.zulipchat.com
  19
  20
  21 Copyright (c) 2001-2019 Python Software Foundation.  All rights reserved.
  22
  23 See the end of this file for further copyright and license information.
  24
  25 .. contents::
  26
  27 General Information
  28 -------------------
  29
  30 - Website: https://www.python.org
  31 - Source code: https://github.com/python/cpython
  32 - Issue tracker: https://bugs.python.org
  33 - Documentation: https://docs.python.org
  34 - Developer's Guide: https://devguide.python.org/
  35
  36 Contributing to CPython
  37 -----------------------
  38
  39 For more complete instructions on contributing to CPython development,
  40 see the `Developer Guide`_.
  41
  42 .. _Developer Guide: https://devguide.python.org/
  43
  44 Using Python
  45 ------------
  46
  47 Installable Python kits, and information about using Python, are available at
  48 `python.org`_.
  49
  50 .. _python.org: https://www.python.org/
  51
  52 Build Instructions
  53 ------------------
  54
  55 On Unix, Linux, BSD, macOS, and Cygwin::
  56
  57     ./configure
  58     make
  59     make test
  60     sudo make install
  61
  62 This will install Python as ``python3``.
  63
  64 You can pass many options to the configure script; run ``./configure --help``
  65 to find out more.  On macOS and Cygwin, the executable is called ``python.exe``;
  66 elsewhere it's just ``python``.
  67
  68 If you are running on macOS with the latest updates installed, make sure to install
  69 OpenSSL or some other SSL software along with Homebrew or another package manager.
  70 If issues persist, see https://devguide.python.org/setup/#macos-and-os-x for more
  71 information.
  72
  73 On macOS, if you have configured Python with ``--enable-framework``, you
  74 should use ``make frameworkinstall`` to do the installation.  Note that this
  75 installs the Python executable in a place that is not normally on your PATH,
  76 you may want to set up a symlink in ``/usr/local/bin``.
  77
  78 On Windows, see `PCbuild/readme.txt
  79 <https://github.com/python/cpython/blob/master/PCbuild/readme.txt>`_.
  80
  81 If you wish, you can create a subdirectory and invoke configure from there.
  82 For example::
  83
  84     mkdir debug
  85     cd debug
  86     ../configure --with-pydebug
  87     make
  88     make test
  89
  90 (This will fail if you *also* built at the top-level directory.  You should do
  91 a ``make clean`` at the top-level first.)
  92
  93 To get an optimized build of Python, ``configure --enable-optimizations``
  94 before you run ``make``.  This sets the default make targets up to enable
  95 Profile Guided Optimization (PGO) and may be used to auto-enable Link Time
  96 Optimization (LTO) on some platforms.  For more details, see the sections
  97 below.
  98
  99
 100 Profile Guided Optimization
 101 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 102
 103 PGO takes advantage of recent versions of the GCC or Clang compilers.  If used,
 104 either via ``configure --enable-optimizations`` or by manually running
 105 ``make profile-opt`` regardless of configure flags, the optimized build
 106 process will perform the following steps:
 107
 108 The entire Python directory is cleaned of temporary files that may have
 109 resulted from a previous compilation.
 110
 111 An instrumented version of the interpreter is built, using suitable compiler
 112 flags for each flavour. Note that this is just an intermediary step.  The
 113 binary resulting from this step is not good for real life workloads as it has
 114 profiling instructions embedded inside.
 115
 116 After the instrumented interpreter is built, the Makefile will run a training
 117 workload.  This is necessary in order to profile the interpreter execution.
 118 Note also that any output, both stdout and stderr, that may appear at this step
 119 is suppressed.
 120
 121 The final step is to build the actual interpreter, using the information
 122 collected from the instrumented one.  The end result will be a Python binary
 123 that is optimized; suitable for distribution or production installation.
 124
 125
 126 Link Time Optimization
 127 ^^^^^^^^^^^^^^^^^^^^^^
 128
 129 Enabled via configure's ``--with-lto`` flag.  LTO takes advantage of the
 130 ability of recent compiler toolchains to optimize across the otherwise
 131 arbitrary ``.o`` file boundary when building final executables or shared
 132 libraries for additional performance gains.
 133
 134
 135 What's New
 136 ----------
 137
 138 We have a comprehensive overview of the changes in the `What's New in Python
 139 3.9 <https://docs.python.org/3.9/whatsnew/3.9.html>`_ document.  For a more
 140 detailed change log, read `Misc/NEWS
 141 <https://github.com/python/cpython/blob/master/Misc/NEWS.d>`_, but a full
 142 accounting of changes can only be gleaned from the `commit history
 143 <https://github.com/python/cpython/commits/master>`_.
 144
 145 If you want to install multiple versions of Python, see the section below
 146 entitled "Installing multiple versions".
 147
 148
 149 Documentation
 150 -------------
 151
 152 `Documentation for Python 3.9 <https://docs.python.org/3.9/>`_ is online,
 153 updated daily.
 154
 155 It can also be downloaded in many formats for faster access.  The documentation
 156 is downloadable in HTML, PDF, and reStructuredText formats; the latter version
 157 is primarily for documentation authors, translators, and people with special
 158 formatting requirements.
 159
 160 For information about building Python's documentation, refer to `Doc/README.rst
 161 <https://github.com/python/cpython/blob/master/Doc/README.rst>`_.
 162
 163
 164 Converting From Python 2.x to 3.x
 165 ---------------------------------
 166
 167 Significant backward incompatible changes were made for the release of Python
 168 3.0, which may cause programs written for Python 2 to fail when run with Python
 169 3.  For more information about porting your code from Python 2 to Python 3, see
 170 the `Porting HOWTO <https://docs.python.org/3/howto/pyporting.html>`_.
 171
 172
 173 Testing
 174 -------
 175
 176 To test the interpreter, type ``make test`` in the top-level directory.  The
 177 test set produces some output.  You can generally ignore the messages about
 178 skipped tests due to optional features which can't be imported.  If a message
 179 is printed about a failed test or a traceback or core dump is produced,
 180 something is wrong.
 181
 182 By default, tests are prevented from overusing resources like disk space and
 183 memory.  To enable these tests, run ``make testall``.
 184
 185 If any tests fail, you can re-run the failing test(s) in verbose mode.  For
 186 example, if ``test_os`` and ``test_gdb`` failed, you can run::
 187
 188     make test TESTOPTS="-v test_os test_gdb"
 189
 190 If the failure persists and appears to be a problem with Python rather than
 191 your environment, you can `file a bug report <https://bugs.python.org>`_ and
 192 include relevant output from that command to show the issue.
 193
 194 See `Running & Writing Tests <https://devguide.python.org/runtests/>`_
 195 for more on running tests.
 196
 197 Installing multiple versions
 198 ----------------------------
 199
 200 On Unix and Mac systems if you intend to install multiple versions of Python
 201 using the same installation prefix (``--prefix`` argument to the configure
 202 script) you must take care that your primary python executable is not
 203 overwritten by the installation of a different version.  All files and
 204 directories installed using ``make altinstall`` contain the major and minor
 205 version and can thus live side-by-side.  ``make install`` also creates
 206 ``${prefix}/bin/python3`` which refers to ``${prefix}/bin/pythonX.Y``.  If you
 207 intend to install multiple versions using the same prefix you must decide which
 208 version (if any) is your "primary" version.  Install that version using ``make
 209 install``.  Install all other versions using ``make altinstall``.
 210
 211 For example, if you want to install Python 2.7, 3.6, and 3.9 with 3.9 being the
 212 primary version, you would execute ``make install`` in your 3.9 build directory
 213 and ``make altinstall`` in the others.
 214
 215
 216 Issue Tracker and Mailing List
 217 ------------------------------
 218
 219 Bug reports are welcome!  You can use the `issue tracker
 220 <https://bugs.python.org>`_ to report bugs, and/or submit pull requests `on
 221 GitHub <https://github.com/python/cpython>`_.
 222
 223 You can also follow development discussion on the `python-dev mailing list
 224 <https://mail.python.org/mailman/listinfo/python-dev/>`_.
 225
 226
 227 Proposals for enhancement
 228 -------------------------
 229
 230 If you have a proposal to change Python, you may want to send an email to the
 231 comp.lang.python or `python-ideas`_ mailing lists for initial feedback.  A
 232 Python Enhancement Proposal (PEP) may be submitted if your idea gains ground.
 233 All current PEPs, as well as guidelines for submitting a new PEP, are listed at
 234 `python.org/dev/peps/ <https://www.python.org/dev/peps/>`_.
 235
 236 .. _python-ideas: https://mail.python.org/mailman/listinfo/python-ideas/
 237
 238
 239 Release Schedule
 240 ----------------
 241
 242 See :pep:`596` for Python 3.9 release details.
 243
 244
 245 Copyright and License Information
 246 ---------------------------------
 247
 248 Copyright (c) 2001-2019 Python Software Foundation.  All rights reserved.
 249
 250 Copyright (c) 2000 BeOpen.com.  All rights reserved.
 251
 252 Copyright (c) 1995-2001 Corporation for National Research Initiatives.  All
 253 rights reserved.
 254
 255 Copyright (c) 1991-1995 Stichting Mathematisch Centrum.  All rights reserved.
 256
 257 See the file "LICENSE" for information on the history of this software, terms &
 258 conditions for usage, and a DISCLAIMER OF ALL WARRANTIES.
 259
 260 This Python distribution contains *no* GNU General Public License (GPL) code,
 261 so it may be used in proprietary projects.  There are interfaces to some GNU
 262 code but these are entirely optional.
 263
 264 All trademarks referenced herein are property of their respective holders.