update instructions for installing from source

[cjchapman]

resolves #675
[no CI]

[frankrolf]

I was about to ask “Are we really removing the simple python setup.py install – which works for Python 2”, but then I realized we probably don’t want to encourage Python 2 use anyway.

[frankrolf]

LGTM.
I’d still like to know why the normal install won’t work with Python 3.

[cjchapman]

The wheel-based instructions work for both Python 2 & 3.

The basic install instructions don't work because they're meant for Python-only installation, not the sort of hybrid C-binaries + Python installation that we're doing. At least, that's my understanding of the problem.

[anthrotype]

The way the afdko's setup.py uses the scripts keyword of setuptools.setup() function is unconventional, in that it installs binary C executables to the bin/ or Scripts/ folder, whereas these are originally designed to be text-based scripts (either written in python or some shell scripting languages). This has been the case for distutils and then also for setuptools which extends distutils.
The result of this is that using setup.py install or setup.py develop commands is currently broken for the afdko. On the other hand, these methods of installation are being superseded by pip, which has taken on the responsibilities of the easy_install module from setuptools, de facto deprecated.

Building a wheel from a local source checkout and then installing that, simply works around this because it avoids calling easy_install but uses pip to install the content of the wheel, which is simply unzipped to destination as is. When building the wheel, the afdko setup.py overrides the distutils build_scripts command so that it will not attempt to adjust the #!shebang (as they are not text files after all). When running setup.py install/develop, the easy_install module takes care of installing the executable scripts but doesn't call from the custom build_scripts command, so it fails because it expects text but finds binary blobs.

To cut it short.. the recommended way to install from a local source checkout is pip install ., provided that the wheel module is also installed in the current python environment (it always is when working from within a virtualenv, but not automatically when creating a python3 -m venv). Of course, wheel is a pre-requisite of python setup.py bdist_wheel command.
When wheel is available, and pip is installing from a local source checkout that has a setup.py script, a a wheel is first built and then installed, and may also be cached for subsequent installs in pip's cache.

pip wheel --wheel-dir dist --no-deps . (where dot means the current directory where the afdko source supposedly is) can be used in alternative to calling python setup.py bdist_wheel directly. The latter command is called by pip wheel, but from a clean temporary directory, and thus doesn't leave extra built artifacts in the source tree. The generated wheel file will be saved in the dist folder. Without --no-deps all the dependencies will also be either downloaded as wheels from PyPI or built from source distribution into a wheel.

[cjchapman]

@anthrotype Would you please cut-and-paste your text above into #675, so if someone finds that issue, they'll get all the info? Thanks!

[anthrotype]

the only thing really missing from this wheel-based setup is the ability to pip install in --editable mode, which is the same as doing python setup.py develop. But this only impacts the few core afdko developers that need to work on the sources as they modify them, and they can use alternative methods like exporting a PYTHONPATH, or using .pth file or similar hacks

[anthrotype]

i'd suggest something like:

ensure the `wheel` module is installed (`pip install wheel`), then cd to the top-level directory of the afdko, and run:
    pip install .

[anthrotype]

bonus point, with an additional note saying that pip install -e . doesn't work for the reasons explained above.

[miguelsousa]

what Cosimo suggested

[cjchapman]

@miguelsousa and @anthrotype I don't understand what you guys are talking about and I'm trying to focus on the refactoring of tx, rotatefont, & mergefonts right now, so I'd be grateful if one of you could update the readme with whatever wording you think is appropriate.

[miguelsousa]

Will do.