build/docs/python.rst

   1 .. _python:
   2
   3 ===========================
   4 Python and the Build System
   5 ===========================
   6
   7 The Python programming language is used significantly in the build
   8 system. If we need to write code for the build system or for a tool
   9 related to the build system, Python is typically the first choice.
  10
  11 Python Requirements
  12 ===================
  13
  14 The tree requires Python 3.7 or greater to build.
  15 All Python packages not in the Python distribution are included in the
  16 source tree. So all you should need is a vanilla Python install and you
  17 should be good to go.
  18
  19 Only CPython (the Python distribution available from www.python.org) is
  20 supported.
  21
  22 Compiled Python Packages
  23 ========================
  24
  25 There are some features of the build that rely on compiled Python packages
  26 (packages containing C source). These features are currently all
  27 optional because not every system contains the Python development
  28 headers required to build these extensions.
  29
  30 We recommend you have the Python development headers installed (``mach
  31 bootstrap`` should do this for you) so you can take advantage of these
  32 features.
  33
  34 Issues with OS X System Python
  35 ==============================
  36
  37 The Python that ships with OS X has historically been littered with
  38 subtle bugs and suboptimalities.
  39
  40 OS X 10.8 and below users will be required to install a new Python
  41 distribution. This may not be necessary for OS X 10.9+. However, we
  42 still recommend installing a separate Python because of the history with
  43 OS X's system Python issues.
  44
  45 We recommend installing Python through Homebrew or MacPorts. If you run
  46 ``mach bootstrap``, this should be done for you.
  47
  48 Virtual Environments
  49 ====================
  50
  51 The build system relies heavily on
  52 `venv <https://docs.python.org/3/library/venv.html>`_. Venv provides
  53 standalone and isolated Python "virtual environments". The problem a venv
  54 solves is that of dependencies across multiple Python components. If two
  55 components on a system relied on different versions of a package, there
  56 could be a conflict. Instead of managing multiple versions of a package
  57 simultaneously, Python and venv take the route that it is easier
  58 to just keep them separate so there is no potential for conflicts.
  59
  60 Very early in the build process, a venv is created inside the
  61 :term:`object directory`. The venv is configured such that it can
  62 find all the Python packages in the source tree. The code for this lives
  63 in ``mach.site``.
  64
  65 Deficiencies
  66 ------------
  67
  68 There are numerous deficiencies with the way virtual environments are
  69 handled in the build system.
  70
  71 * mach reinvents the venv.
  72
  73   There is code in ``build/mach_initialize.py`` that configures ``sys.path``
  74   much the same way the venv does. There are various bugs tracking
  75   this. However, no clear solution has yet been devised. It's not a huge
  76   problem and thus not a huge priority.
  77
  78 * They aren't preserved across copies and packaging.
  79
  80   If you attempt to copy an entire tree from one machine to another or
  81   from one directory to another, chances are the venv will fall
  82   apart. It would be nice if we could preserve it somehow. Instead of
  83   actually solving portable venv, all we really need to solve is
  84   encapsulating the logic for populating the venv along with all
  85   dependent files in the appropriate place.
  86
  87 * .pyc files written to source directory.
  88
  89   We rely heavily on ``.pth`` files in our venv. A ``.pth`` file
  90   is a special file that contains a list of paths. Python will take the
  91   set of listed paths encountered in ``.pth`` files and add them to
  92   ``sys.path``.
  93
  94   When Python compiles a ``.py`` file to bytecode, it writes out a
  95   ``.pyc`` file so it doesn't have to perform this compilation again.
  96   It puts these ``.pyc`` files alongside the ``.pyc`` file. Python
  97   provides very little control for determining where these ``.pyc`` files
  98   go, even in Python 3 (which offers customer importers).
  99
 100   With ``.pth`` files pointing back to directories in the source tree
 101   and not the object directory, ``.pyc`` files are created in the source
 102   tree. This is bad because when Python imports a module, it first looks
 103   for a ``.pyc`` file before the ``.py`` file. If there is a ``.pyc``
 104   file but no ``.py`` file, it will happily import the module. This
 105   wreaks havoc during file moves, refactoring, etc.
 106
 107   There are various proposals for fixing this. See bug 795995.
 108
 109 Installing Python Manually
 110 ==========================
 111
 112 We highly recommend you use your system's package manager or a
 113 well-supported 3rd party package manager to install Python for you. If
 114 these are not available to you, we recommend the following tools for
 115 installing Python:
 116
 117 * `buildout.python <https://github.com/collective/buildout.python>`_
 118 * `pyenv <https://github.com/yyuu/pyenv>`_
 119 * An official installer from http://www.python.org.
 120
 121 If all else fails, consider compiling Python from source manually. But this
 122 should be viewed as the least desirable option.
 123
 124 Common Issues with Python
 125 =========================
 126
 127 Upgrading your Python distribution breaks the venv
 128 --------------------------------------------------------
 129
 130 If you upgrade the Python distribution (e.g. install Python 3.6.15
 131 from 3.6.9), chances are parts of the venv will break.
 132 This commonly manifests as a cryptic ``Cannot import XXX`` exception.
 133 More often than not, the module being imported contains binary/compiled
 134 components.
 135
 136 If you upgrade or reinstall your Python distribution, we recommend
 137 clobbering your build.
 138
 139 Packages installed at the system level conflict with build system's
 140 -------------------------------------------------------------------
 141
 142 It is common for people to install Python packages using ``sudo`` (e.g.
 143 ``sudo pip install psutil``) or with the system's package manager
 144 (e.g. ``apt-get install python-mysql``.
 145
 146 A problem with this is that packages installed at the system level may
 147 conflict with the package provided by the source tree. As of bug 907902
 148 and changeset f18eae7c3b27 (September 16, 2013), this should no longer
 149 be an issue since the venv created as part of the build doesn't
 150 add the system's ``site-packages`` directory to ``sys.path``. However,
 151 poorly installed packages may still find a way to creep into the mix and
 152 interfere with our venv.
 153
 154 As a general principle, we recommend against using your system's package
 155 manager or using ``sudo`` to install Python packages. Instead, create
 156 virtual environments and isolated Python environments for all of your
 157 Python projects.
 158
 159 Python on $PATH is not appropriate
 160 ----------------------------------
 161
 162 Tools like ``mach`` will look for Python by performing ``/usr/bin/env
 163 python`` or equivalent. Please be sure the appropriate Python 2.7.3+
 164 path is on $PATH. On OS X, this likely means you'll need to modify your
 165 shell's init script to put something ahead of ``/usr/bin``.