admin/brew
1
0
Fork 0
Code Issues Packages Projects Releases 6 Wiki Activity

docs: recommend setup_install_args instead of setup_install

Browse Source 
Closes Homebrew/homebrew#34793.
This commit is contained in:
Tim D. Smith 2014-12-10 12:27:46 -08:00
parent 65a7a631ea
commit c5c4684714
1 changed files with 13 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
share/doc/homebrew/Python-for-Formula-Authors.md
View File

@ -12,13 +12,13 @@ Homebrew is happy to accept applications that are built in Python, whether the a
# Running setup.py
Homebrew provides a helper method, `Language::Python.setup_install`, for invoking `setup.py`. Please use it instead of invoking `setup.py` directly. The syntax is:
Homebrew provides a helper method, `Language::Python.setup_install_args`, which returns arguments for invoking setup.py. Please use it instead of invoking `setup.py` explicitly. The syntax is:
```ruby
Language::Python.setup_install python, prefix, *args
system "python", *Language::Python.setup_install_args(prefix)
```
where `python` is either `"python"` or `"python3"`, `prefix` is the destination prefix (usually `libexec` or `prefix`), and `*args` is one or more additional arguments to be passed to `setup.py` after `install`.
where `prefix` is the destination prefix (usually `libexec` or `prefix`).
# Python module dependencies
@ -60,9 +60,9 @@ In your formula's `install` method, first set the `PYTHONPATH` environment varia
```ruby
ENV.prepend_path "PYTHONPATH", libexec/"lib/python2.7/site-packages"
```
Then, use `Language::Python.setup_install` to invoke `setup.py` like:
Then, use `system` with `Language::Python.setup_install_args` to invoke `setup.py` like:
```ruby
Language::Python.setup_install "python", libexec
system "python", *Language::Python.setup_install_args(libexec)
```
This will have placed the scripts your Python package installs in `libexec/"bin"`, which is not symlinked into Homebrew's prefix. We need to make sure these are installed and we also need to make sure that, when they are invoked, `PYTHONPATH` includes the path where we just installed your package. Do this with:
@ -85,7 +85,7 @@ ENV.prepend_path "PYTHONPATH", libexec/"vendor/lib/python2.7/site-packages"
```
before staging and installing each resourced dependency with:
```ruby
Language::Python.setup_install "python", libexec/"vendor"
system "python", *Language::Python.setup_install_args(libexec/"vendor")
```
## Example
@ -109,11 +109,13 @@ class Foo < Formula
def install
ENV.prepend_path "PYTHONPATH", libexec/"vendor/lib/python2.7/site-packages"
%w[six parsedatetime].each do |r|
resource(r).stage { Language::Python.setup_install "python", libexec/"vendor" }
resource(r).stage do
system "python", *Language::Python.setup_install_args(libexec/"vendor")
end
end
ENV.prepend_path "PYTHONPATH", libexec/"lib/python2.7/site-packages"
Language::Python.setup_install "python", libexec
system "python", *Language::Python.setup_install_args(libexec)
bin.install Dir[libexec/"bin/*"]
bin.env_script_all_files(libexec/"bin", :PYTHONPATH => ENV["PYTHONPATH"])
@ -136,7 +138,7 @@ Bindings should follow the same advice for Python module dependencies as librari
If the bindings are installed by invoking a `setup.py`, do something like:
```ruby
cd "source/python" do
Language::Python.setup_install "python", prefix
system "python", *Language::Python.setup_install_args(prefix)
end
```
@ -146,7 +148,7 @@ If the `configure` and `make` scripts do not want to install into the Cellar, so
1. Call `./configure --without-python` (or a similar named option)
1. `cd` into the directory containing the Python bindings
1. Call `setup.py` with `Language::Python.setup_install` (as described above)
1. Call `setup.py` with `system` and `Language::Python.setup_install_args` (as described above)
Sometimes we have to `inreplace` a `Makefile` to use our prefix for the python bindings. (`inreplace` is one of Homebrew's helper methods, which greps and edits text files on-the-fly.)
@ -196,7 +198,7 @@ Distribute (not to be confused with distutils) is an obsolete fork of setuptools
setuptools requires that SVEM is used in conjunction with `--record`, which provides a list of files that can later be used to uninstall the package. We don't need or want this because Homebrew can manage uninstallation but since setuptools demands it we comply. The Homebrew convention is to call the record file "installed.txt".
Detecting whether a `setup.py` uses `setup()` from setuptools or distutils is difficult, but we always need to pass this flag to setuptools-based scripts. `pip` faces the same problem that we do and forces `setup()` to use the setuptools version by loading a shim around `setup.py` that imports setuptools before doing anything else. Since setuptools monkey-patches distutils and replaces its `setup` function, this provides a single, consistent interface. We have borrowed this code and use it in `Language::Python.setup_install`.
Detecting whether a `setup.py` uses `setup()` from setuptools or distutils is difficult, but we always need to pass this flag to setuptools-based scripts. `pip` faces the same problem that we do and forces `setup()` to use the setuptools version by loading a shim around `setup.py` that imports setuptools before doing anything else. Since setuptools monkey-patches distutils and replaces its `setup` function, this provides a single, consistent interface. We have borrowed this code and use it in `Language::Python.setup_install_args`.
## `--prefix` vs `--root`