Building and installing

From PyPI

Binary Python wheels are built and distributed on PyPI for the following Python versions:

Architecture	Windows	Linux	MacOS
x86	3.7-3.11	N/A	3.7-3.11
x64	3.7-3.11	3.7-3.11	3.7-3.11

On these systems python3 -m pip install endplay will install these pre-built wheels, otherwise it will attempt to install from the source distribution which requires a C++ compiler on your system. Note that endplay requires Python 3.7+.

The version of the library available on PyPI may be older than the current status of the repo, this is to ensure stability of these builds. For access to the latest bug fixes and preview features, you can install directly from the GitHub repo with python3 -m pip install +git:https://github.com/dominicprice/endplay

From source

endplay uses setuptools to manage its build and can be installed with pip.

# Clone repo and submodules
git clone --recursive https://github.com/dominicprice/endplay.git
cd endplay
python3 -m pip install .

If you want to build the binary wheels for your system, you can use the build package. This will create an isolated environment when collecting packages so you do not need to perform this in a virtual environment.

# Only build is required to start the build, other packages
# are automatically fetched
python3 -m pip install build
python3 -m build # generates dist/endplay-<VERSIONSUFFIX>.whl

For development

If you are trying to develop for the library, then it is recommended to do all your testing in a virtual environment:

python3 -m pip install virtualenv
virtualenv venv
source venv/bin/activate # on windows, `cmd venv\scripts\activate`
python -m pip install . # installs into the created venv

You can then modify some files, and when you want to debug simply rerun python -m pip install . and the old build will be overwritten. This also has the advantage of being able to reuse the cache from the previous install (including the CMake cache) which speeds up build time.

If you are not planning on modifying the underlying C library, its packaging logic or the config file, then you can avoid having to reinstall each time by making an in-source build and symlinking this into your site packages. The simplest way to do this is to run the following from the root directory:

mkdir build && cd build
cmake -DCMAKE_INSTALL_PREFIX=../src ..
cmake --build . --target install
cd ../src
pwd > "$(python -m site --user-site)/endplay.pth"

The last command will work on POSIX systems, on Windows you can get the site packages directory by running python -m site --user-site and creating a file endplay.pth there with a single line containing the absolute path to <ENDPLAY_ROOT>/src.

The .gitignore is set up to ignore the files CMake installs so no extra care needs to be taken when staging and committing your changes to git.

Building the documentation

The documentation is semi-auto generated with sphinx. To build it, ensure that endplay is installed and then cd into the root directory and then run

cd docs
make html # or latex, or whatever output format you want

The documentation will be built in the build directory.

Running the test suite

The test suite is implemented with the unittest library and can be run from the root directory with

python3 -m pytest