Skip to content

Latest commit

 

History

History
229 lines (148 loc) · 7.92 KB

README.md

File metadata and controls

229 lines (148 loc) · 7.92 KB
Raw

Building VoteTrackerPlus

Follow the steps in this section to build VTP. Unless you make changes to the source you will not need to do this more than once.

1) Pre-requisites

For all these build setups you will need the following tools:

  • Python. You will need Python >= 3.8

    If you are using an older Python and are not sure how to install a more recent one look at RealPython's Managing Multiple Python Versions with pyenv.

  • Pip. You will usually need Pip >= 21.3

    Check your Pip version:

        $ pip -V

    If you are on an older Pip, then after installing and activating the virtual environment run:

        $ pip install --upgrade pip

2) Building/creating a local install

To build VTP, you need to:

  1. Start at the root of the cloned source tree.
  2. Create a Python virtual environment
  3. Activate the virtual environment
  4. Upgrade to a recent Pip.
  5. Build the package using an a local project install (aka as an editable install).

Multiple Python build systems can be used to support the last step. VTP currently supports Poetry (recommended as it will be simpler) and Setuptools (on older or legacy systems).

2.1) Build with Poetry

If you are able to use a recent Python setup (since mid-2020) build with Poetry. You will need Poetry >= 1.1.

To install Poetry see: https://python-poetry.org/docs/1.1/#installation

You can check your Poetry version with:

    $ poetry --version

Then build VTP as follows:

    $ ln -s _tools/build/poetry_pyproject.toml pyproject.toml
    $ ln -s _tools/build/poetry_poetry.lock poetry.lock
    $ poetry shell
    $ poetry install

There is a makefile at the root of the git repo that can run this local install build:

    $ make poetry-build

2.2) Build with Setuptools

If you are running on older systems installed since 2019 (including Ubuntu 20.04 without upgrades) or are otherwise limited to Setuptools, after activating the virtual environment use Pip to see if you have Setuptools:

    $ pip freeze | grep setuptools

If there is no Setuptools use Pip to install it:

    $ pip install setuptools

If Setuptools is present but not >= 64.0.0, use Pip to upgrade it:

    $ pip install --upgrade setuptools

2.2a) Build with Current/Recent Setuptools

Then build VTP as follows:

    $ ln -s _tools/build/setuptools_pyproject.toml pyproject.toml
    $ python -m venv .venv
    $ source .venv/bin/activate
    $ pip install --editable .

Note: Don't leave the . off of the pip install . There is also a makefile at the root of the git repo that can run this local install build:

    $ make setuptools-build

2.2b) Build with Legacy Setuptools

If you can't upgrade Setuptools for any reason, then you should build as follows:

    $ ln -s _tools/build/setuptools_legacy_pyproject.toml pyproject.toml
    $ ln -s _tools/build/setuptools_legacy_setup.cfg setup.cfg
    $ python -m venv .venv
    $ source .venv/bin/activate
    $ pip install --editable .

There is a makefile at the root of the git repo that can run this local install build:

    $ make setuptools-legacy-build

3) Concepts

  • Editable installs

    Python editable installs ensure that all import statements, both inside the project and in external packages point to the same python files, and make it so that all paths and scripts just work. Note that is all per python environment. Multiple python environments work as expected but that level of sophistication is not described here.

    Editable installs are usually run with Pip:

        $ pip install --editable <project directory>

    Poetry does editable installs by default.

        $ poetry install

    The actual work is done by a build tool which supports PEP 660. This includes Setuptools >= 64.0.0 and Poetry >= 1.1.0.

  • pyproject.toml

    Modern Python packaging introduces a single configuration file for managing the building and packaging of a Python project. This file, called pyproject.toml allows specifying builds using any of a number of different packaging and build backends.

    pyproject.toml specifies the build backend in a section called build-system. See the Poetry build system and the Setuptools build system

    Poetry and Setuptools support pyproject.toml. A number of other build tools do as well.

    To learn more about pyproject.toml read PEP 518and PEP 621.

  • setup.cfg

    An older configuration file supported only by Setuptools. In versions of Setuptools that don't support PEP 660 pyproject.toml is mostly empty, and the work of configuration is done by setup.cfg.

    It's preferrable not to need setup.cfg as it's not compatible with any other build tools, but on older systems that may be the only available choice.

4) References

4.1) Guides

To learn about packaging in general read thePython Packaging User Guide

To learn about the tools:

  • Pip
    • [Pip User Guide][pip-userguide]
  • Poetry
  • Setuptools
    • [Setuptools User Guide][setuptools-user-guide]

Read about editable installs:

4.2) Specifications

  • PEP 517: Build-System Independent Format or Source Trees

    Defines the API between Python build system frontends and backends.

  • PEP 518: Specifying Minimum Build System Requirements for Python Projects

    Defines pyproject.toml, and its build-system section.

  • PEP 621: _Storing Project Metadata in pyproject.toml

    Defines the metadata properties (key names and value types) that can be used for projects across Python build systems.

  • PEP 660: Editable installs for pyproject.toml based builds

    Defines the API providing portable editable installs between build backends.

As one additional TL;DR note - though the PEP 660 describes the VoteTracker+ poetry local install, in the case of a generic MacOS install, assuming a default installation of just about everything, the poetry local install ends up placing the local install files in the following location:

/Users/<USER>/Library/Caches/pypoetry/virtualenvs/votetrackerplus-<UID>-py3.9/lib/
    python3.x/site-packages/votetrackerplus.pth
                            votetrackerplus-0.x.y-distinfo/entry_points.txt
                                                           INSTALLER
                                                           METADATA
                                                           RECORD

The above includes SHA-256 digests of the install files beyond/outside of what git/GitHub is tracking.