Development Setup

The development workflow is still being worked on, but this page covers the current state of the world.

You will see pip install -e . frequently in the documentation. Please see the pip documentation for an explanation on what this does.

Backend Development

Windows

  • Included

    • C++ Build Tools core features

    • C++ 2022 Redistributable Update

    • C++ core desktop features

  • Optional

    • MSVC v143 - VS 2022 C++ x64/x86 build tools (vXX,XX)

    • Windows SDK (10.0.XXXXX.X)

    • C++ CMake tools for Windows

    • Testing tools core features - Build Tools

    • C++ AddressSanitizer

  • Default install options are appropriate - go get some coffee

  • Reboot

$ py -m venv C:\ledfx
$ cd C:\ledfx
$ .\Scripts\activate.bat
$ pip install wheel
$ pip install pywin32
$ python .\Scripts\pywin32_postinstall.py -install
$ git clone https://github.com/LedFx/LedFx.git .\ledfx-git
$ cd .\ledfx-git

Manual call to requirements.txt is a temporary step as we need to fix up setup.py

We need to install numpy first, or aubio will not be happy

$ pip install numpy==1.23.5
$ pip install -r requirements.txt
$ python setup.py develop
$ ledfx --open-ui

1. To develop, open up a terminal and activate the ledfx virtual environment

$ C:\ledfx\Scripts\activate.bat

2. Make changes to LedFx’s files in C:/ledfx/ledfx-git. Your changed files will be run when you run LedFx

$ ledfx --open-ui

You can keep the ledfx virtual environment open and keep making changes then running ledfx. No need to reactivate the virtual environment between changes.

Linux

1. Clone the main branch from the LedFx Github repository:

$ git clone https://github.com/LedFx/LedFx.git
$ cd LedFx

2. Install system dependencies via apt install:

$ sudo apt install libatlas3-base \
      libavformat58 \
      portaudio19-dev \
      pulseaudio

3. Install LedFx and its requirements using pip:

$ pip install -r requirements-dev.txt
$ pip install -e .

4. This will let you run LedFx directly from your Git repository via:

$ ledfx --open-ui

macOS

1. Clone the main branch from the LedFx Github repository:

$ git clone https://github.com/LedFx/LedFx.git
$ cd ./LedFx

2. Create a python venv for LedFx with python>=3.7 and install dependencies:

$ python3 -m venv ~/ledfx-venv
$ source ~/ledfx-venv/bin/activate
$ brew install portaudio pulseaudio

3. Install LedFx and its requirements using pip:

$ pip install -r requirements-dev.txt
$ pip install -e .

4. This will let you run LedFx directly from your Git repository via:

$ ledfx --open-ui

Frontend Development

Building the LedFx frontend is different from how the core backend is built. The frontend is based on React.js and thus uses NPM as the core package management.

Note

LedFx will need to be running in development mode for everything to work. To enable development mode, open the config.json file in the .ledfx folder and set dev_mode: true)

Linux

Note

The following instructions assume you have already followed the steps above to install the LedFx dev environment

To get started, first install npm and all the requirements:

1. Start in the LedFx repo directory:

$ pip install yarn
$ cd frontend
$ yarn

The easiest way to test and validate your changes is to run a watcher that will automatically rebuild as you save and then just leave LedFx running in a separate command window.

2. Start LedFx in development mode and start the watcher:

$ python3 ledfx
$ yarn start

At that point any change you make to the frontend will be recompiled and after a browser refresh LedFx will pick up the new files. After development and testing you will need to run a full build to generate the appropriate distribution files prior to submitting any changes.

3. When you are finished with your changes, build the frontend:

$ yarn build

macOS

Note

The following instructions assume you have already followed the steps above to install the LedFx dev environment

1. Install nodejs and NPM requirements using homebrew:

$ brew install nodejs
$ brew install yarn
$ cd ~/frontend
$ yarn

2. Start LedFx in developer mode and start the NPM watcher:

$ python3 ledfx
$ yarn start

3. When you are finished with your changes, build the frontend:

$ yarn build

Document Development

The documentation is written in reStructuredText. Once you are finished making changes, you must build the documentation. To build the LedFx documentation follow the steps outlined below:

Note

Alternatively, you may run make livehtml in place of make html to open a browser and view your changes in realtime.

Linux

$ cd ~/ledfx/docs
$ pip install -r requirements-docs.txt
$ make html

macOS

$ source ~/ledfx-venv/bin/activate
$ cd ~/ledfx/docs
$ pip install -r requirements-docs.txt
$ make html