mirror of
https://github.com/pyenv/pyenv.git
synced 2024-11-21 20:47:00 -05:00
222 lines
8.8 KiB
Markdown
222 lines
8.8 KiB
Markdown
# python-build
|
|
|
|
python-build is a [pyenv](https://github.com/pyenv/pyenv) plugin that
|
|
provides a `pyenv install` command to compile and install different versions
|
|
of Python on UNIX-like systems.
|
|
|
|
You can also use python-build without pyenv in environments where you need
|
|
precise control over Python version installation.
|
|
|
|
See the [list of releases](https://github.com/pyenv/pyenv/releases)
|
|
for changes in each version.
|
|
|
|
|
|
## Installation
|
|
|
|
### Installing as a pyenv plugin (recommended)
|
|
|
|
You need nothing to do since python-build is bundled with pyenv by
|
|
default.
|
|
|
|
### Installing as a standalone program (advanced)
|
|
|
|
Installing python-build as a standalone program will give you access to the
|
|
`python-build` command for precise control over Python version installation. If you
|
|
have pyenv installed, you will also be able to use the `pyenv install` command.
|
|
|
|
git clone git://github.com/pyenv/pyenv.git
|
|
cd pyenv/plugins/python-build
|
|
./install.sh
|
|
|
|
This will install python-build into `/usr/local`. If you do not have write
|
|
permission to `/usr/local`, you will need to run `sudo ./install.sh` instead.
|
|
You can install to a different prefix by setting the `PREFIX` environment
|
|
variable.
|
|
|
|
To update python-build after it has been installed, run `git pull` in your cloned
|
|
copy of the repository, then re-run the install script.
|
|
|
|
### Installing with Homebrew (for OS X users)
|
|
|
|
Mac OS X users can install python-build with the [Homebrew](http://brew.sh)
|
|
package manager. This will give you access to the `python-build` command. If you
|
|
have pyenv installed, you will also be able to use the `pyenv install` command.
|
|
|
|
*This is the recommended method of installation if you installed pyenv with
|
|
Homebrew.*
|
|
|
|
brew install pyenv
|
|
|
|
Or, if you would like to install the latest development release:
|
|
|
|
brew install --HEAD pyenv
|
|
|
|
|
|
## Usage
|
|
|
|
Before you begin, you should ensure that your build environment has the proper
|
|
system dependencies for compiling the wanted Python Version (see our [recommendations](https://github.com/pyenv/pyenv/wiki#suggested-build-environment)).
|
|
|
|
### Using `pyenv install` with pyenv
|
|
|
|
To install a Python version for use with pyenv, run `pyenv install` with
|
|
exact name of the version you want to install. For example,
|
|
|
|
pyenv install 2.7.4
|
|
|
|
Python versions will be installed into a directory of the same name under
|
|
`~/.pyenv/versions`.
|
|
|
|
To see a list of all available Python versions, run `pyenv install --list`. You
|
|
may also tab-complete available Python versions if your pyenv installation is
|
|
properly configured.
|
|
|
|
### Using `python-build` standalone
|
|
|
|
If you have installed python-build as a standalone program, you can use the
|
|
`python-build` command to compile and install Python versions into specific
|
|
locations.
|
|
|
|
Run the `python-build` command with the exact name of the version you want to
|
|
install and the full path where you want to install it. For example,
|
|
|
|
python-build 2.7.4 ~/local/python-2.7.4
|
|
|
|
To see a list of all available Python versions, run `python-build --definitions`.
|
|
|
|
Pass the `-v` or `--verbose` flag to `python-build` as the first argument to see
|
|
what's happening under the hood.
|
|
|
|
### Custom definitions
|
|
|
|
Both `pyenv install` and `python-build` accept a path to a custom definition file
|
|
in place of a version name. Custom definitions let you develop and install
|
|
versions of Python that are not yet supported by python-build.
|
|
|
|
See the [python-build built-in definitions](https://github.com/pyenv/pyenv/tree/master/plugins/python-build/share/python-build) as a starting point for
|
|
custom definition files.
|
|
|
|
[definitions]: https://github.com/pyenv/pyenv/tree/master/plugins/python-build/share/python-build
|
|
|
|
### Special environment variables
|
|
|
|
You can set certain environment variables to control the build process.
|
|
|
|
* `TMPDIR` sets the location where python-build stores temporary files.
|
|
* `PYTHON_BUILD_BUILD_PATH` sets the location in which sources are downloaded and
|
|
built. By default, this is a subdirectory of `TMPDIR`.
|
|
* `PYTHON_BUILD_CACHE_PATH`, if set, specifies a directory to use for caching
|
|
downloaded package files.
|
|
* `PYTHON_BUILD_MIRROR_URL` overrides the default mirror URL root to one of your
|
|
choosing.
|
|
* `PYTHON_BUILD_SKIP_MIRROR`, if set, forces python-build to download packages from
|
|
their original source URLs instead of using a mirror.
|
|
* `PYTHON_BUILD_ROOT` overrides the default location from where build definitions
|
|
in `share/python-build/` are looked up.
|
|
* `PYTHON_BUILD_DEFINITIONS` can be a list of colon-separated paths that get
|
|
additionally searched when looking up build definitions.
|
|
* `CC` sets the path to the C compiler.
|
|
* `PYTHON_CFLAGS` lets you pass additional options to the default `CFLAGS`. Use
|
|
this to override, for instance, the `-O3` option.
|
|
* `CONFIGURE_OPTS` lets you pass additional options to `./configure`.
|
|
* `MAKE` lets you override the command to use for `make`. Useful for specifying
|
|
GNU make (`gmake`) on some systems.
|
|
* `MAKE_OPTS` (or `MAKEOPTS`) lets you pass additional options to `make`.
|
|
* `MAKE_INSTALL_OPTS` lets you pass additional options to `make install`.
|
|
* `PYTHON_CONFIGURE_OPTS` and `PYTHON_MAKE_OPTS` and `PYTHON_MAKE_INSTALL_OPTS` allow
|
|
you to specify configure and make options for building CPython. These variables
|
|
will be passed to Python only, not any dependent packages (e.g. libyaml).
|
|
|
|
### Applying patches to Python before compiling
|
|
|
|
Both `pyenv install` and `python-build` support the `--patch` (`-p`) flag that
|
|
signals that a patch from stdin should be applied to Python, Jython or PyPy
|
|
source code before the `./configure` and compilation steps.
|
|
|
|
Example usage:
|
|
|
|
```sh
|
|
# applying a single patch
|
|
$ pyenv install --patch 2.7.10 < /path/to/python.patch
|
|
|
|
# applying a patch from HTTP
|
|
$ pyenv install --patch 2.7.10 < <(curl -sSL http://git.io/python.patch)
|
|
|
|
# applying multiple patches
|
|
$ cat fix1.patch fix2.patch | pyenv install --patch 2.7.10
|
|
```
|
|
|
|
|
|
### Building with `--enable-shared`
|
|
|
|
You can build CPython with `--enable-shared` to install a version with
|
|
shared object.
|
|
|
|
If `--enable-shared` was found in `PYTHON_CONFIGURE_OPTS` or `CONFIGURE_OPTS`,
|
|
`python-build` will automatically set `RPATH` to the pyenv's prefix directory.
|
|
This means you don't have to set `LD_LIBRARY_PATH` or `DYLD_LIBRARY_PATH` for
|
|
the version(s) installed with `--enable-shared`.
|
|
|
|
```sh
|
|
$ env PYTHON_CONFIGURE_OPTS="--enable-shared" pyenv install 2.7.9
|
|
```
|
|
|
|
### Checksum verification
|
|
|
|
If you have the `shasum`, `openssl`, or `sha256sum` tool installed, python-build will
|
|
automatically verify the SHA2 checksum of each downloaded package before
|
|
installing it.
|
|
|
|
Checksums are optional and specified as anchors on the package URL in each
|
|
definition. (All bundled definitions include checksums.)
|
|
|
|
### Package download mirrors
|
|
|
|
python-build will first attempt to download package files from a mirror hosted on
|
|
GitHub Pages. If a package is not available on the mirror, if the mirror
|
|
is down, or if the download is corrupt, python-build will fall back to the
|
|
official URL specified in the definition file.
|
|
|
|
You can point python-build to another mirror by specifying the
|
|
`PYTHON_BUILD_MIRROR_URL` environment variable--useful if you'd like to run your
|
|
own local mirror, for example. Package mirror URLs are constructed by joining
|
|
this variable with the SHA2 checksum of the package file.
|
|
|
|
If you don't have an SHA2 program installed, python-build will skip the download
|
|
mirror and use official URLs instead. You can force python-build to bypass the
|
|
mirror by setting the `PYTHON_BUILD_SKIP_MIRROR` environment variable.
|
|
|
|
The official python-build download mirror is provided by
|
|
[GitHub Pages](http://yyuu.github.io/pythons/).
|
|
|
|
### Package download caching
|
|
|
|
You can instruct python-build to keep a local cache of downloaded package files
|
|
by setting the `PYTHON_BUILD_CACHE_PATH` environment variable. When set, package
|
|
files will be kept in this directory after the first successful download and
|
|
reused by subsequent invocations of `python-build` and `pyenv install`.
|
|
|
|
The `pyenv install` command defaults this path to `~/.pyenv/cache`, so in most
|
|
cases you can enable download caching simply by creating that directory.
|
|
|
|
### Keeping the build directory after installation
|
|
|
|
Both `python-build` and `pyenv install` accept the `-k` or `--keep` flag, which
|
|
tells python-build to keep the downloaded source after installation. This can be
|
|
useful if you need to use `gdb` and `memprof` with Python.
|
|
|
|
Source code will be kept in a parallel directory tree `~/.pyenv/sources` when
|
|
using `--keep` with the `pyenv install` command. You should specify the
|
|
location of the source code with the `PYTHON_BUILD_BUILD_PATH` environment
|
|
variable when using `--keep` with `python-build`.
|
|
|
|
|
|
## Getting Help
|
|
|
|
Please see the [pyenv wiki](https://github.com/pyenv/pyenv/wiki) for solutions to common problems.
|
|
|
|
[wiki]: https://github.com/pyenv/pyenv/wiki
|
|
|
|
If you can't find an answer on the wiki, open an issue on the [issue
|
|
tracker](https://github.com/pyenv/pyenv/issues). Be sure to include
|
|
the full build log for build failures.
|