Skip to content

Latest commit

 

History

History
173 lines (122 loc) · 5.95 KB

CONTRIBUTING.md

File metadata and controls

173 lines (122 loc) · 5.95 KB

Contributing

Building from source

Building from source assumes that you have a working installation of Python 3, ideally within a virtual environment.

Building from source: macOS

macOS

To build on macOS from source, install dependencies with Homebrew:

brew install cmake libsndfile libsoundio

Clone this repository, then build and install with pip:

pip3 install .
Building from source: Linux, Raspberry Pi

Linux, Raspberry Pi

SignalFlow supports Linux (verified on Ubuntu 20.04 and Raspberry Pi OS buster) with alsa and pulseaudio backends.

To build the Python library from source on Linux, install dependencies with apt:

apt-get install -y git cmake g++ python3-pip libasound2-dev libsndfile1-dev libsoundio-dev fftw3-dev

If you experience an error on Raspberry Pi libf77blas.so.3: cannot open shared object file:

sudo apt-get install -y libatlas-base-dev

Clone this repository, then build and install with pip:

pip3 install .
Building from source: Windows

Windows

This is work in progress.

Currently, dependencies need to be downloaded and built by hand. These can be placed anywhere.

To build SignalFlow, use the CMake GUI. Press configure and you will see three empty fields to fill in with the path to the two build folders and the FFTW binaries folder (see above). Set these parameters then press Configure, then Generate then Open. Then build in Visual Studio 2019.

As of 2021-03-03, only the signalflow project has been ported to build correctly on Windows. Only tested in x64 and for Debug builds. Tested using Visual Studio 2019.

Building from source: Debug symbols

To build the Python libraries with debug symbols:

python3 setup.py build --debug install
Building from source: C++ only (no Python layer)

To build and install the C++ core without the Python binding layer:

mkdir build
cd build
cmake ..
make -j8

To build with debug symbols, include -DCMAKE_BUILD_TYPE=Debug when calling cmake.

Authoring a new Node

To author a new Node class:

  • Create the .h header file in the appropriate subdirectory of source/include/signalflow/node
  • Create the .cpp source file in the appropriate subdirectory of source/src/node
  • Add the header file to source/include/signalflow/signalflow.h
  • Add the source file to source/src/CMakeLists.txt
  • Regenerate the auto-generated bindings and docs: auxiliary/scripts/auto-generator.py --library --readme --bindings
  • Add unit tests to the appropriate test script in tests
  • Re-run the tests: python3 setup.py test
  • Update the stubs (see Generating stubs)

Note that, to comply with the registry system, all arguments to Node constructors must have default values so that the Node class can be instantiated with a zero-argument syntax, e.g. NodeClass().

Test

To run the unit test suite:

python3 setup.py test

Release

For each new release:

  • Update the version in setup.py
  • Add entry to CHANGELOG.md
  • Commit changes
  • Add a git version tag, in format v1.2.34
  • Add a GitHub release with title v1.2.34, using the latest CHANGELOG entry as the release body
  • Build new wheels:
    • Linux x86: wheels are automatically built using GitHub actions
    • Linux rpi: wheels must be built manually using auxiliary/cibuildwheel/make-raspberry-pi-aarch64.sh
    • macOS: wheels must be built manually using auxiliary/cibuildwheel/make-macos-x86-arm64.sh
    • Windows: wheels must be built manually (TBC)
  • Upload wheels to pypi: twine upload wheelhouse/1.2.34/*

Documentation

To update autogenerated Node documentation:

auxiliary/scripts/auto-generator.py --library --readme

To add examples to the node library, simply add a Python script inside the corresponding Node class's directory inside docs/library. Any .py script found within a node class directory will be automatically included in the markdown documentation by auto-generator.py. By convention, examples are normally named example-0.py, example-1.py, etc.

To generate and render the HTML documentation, install mkdocs and associated plugins:

# use specific mkdocs-material version for full "Last update" text in git revision-date
pip3 install mkdocs mkdocs-material==9.1.15 mkdocs-include-markdown-plugin mkdocs-git-revision-date-localized-plugin

To serve the HTML documentation locally, on http://localhost:8000:

mkdocs serve

To deploy docs to GitHub:

mkdocs gh-deploy

Generating stubs

To generate stubs for IDE type hinting and inline documentation, the pybind11-stubgen package is required. Once installed, run:

pybind11-stubgen -o auxiliary/libs/signalflow-stubs signalflow

The signalflow-stubs package is bundled with the standard SignalFlow wheel, and as per PEP 561's convention for stub-only packages, should be used by IDEs to display type hints and docs. This has been verified in Visual Studio Code 1.84.1.