Development Setup

Backend Development

Warning

Always be aware of piping commands to any shell - this is the recommended method for poetry but there are other options.

Windows

Note

Do not install python from the Windows Store - it will not work with these instructions.

  1. Install python version 3.9 or above.

  2. Install git.

  3. Install Build Tools for Visual Studio 2022

    • When asked for Workloads, select “Desktop development with C++”

    • 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

      • C++ CMake tools for Windows

      • Testing tools core features - Build Tools

      • C++ AddressSanitizer

    • The default install options are appropriate.

  4. Reboot

  5. Install poetry using PowerShell:

    $ (Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

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

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

  7. Install LedFx and its requirements using poetry:

    $ cd LedFx
$ poetry install

  8. This will let you run LedFx directly from the cloned repository via:

    $ poetry run ledfx --open-ui

Linux

Note

This assumes an apt based system such as ubuntu. If your system uses another package manager you should be able use it to get the required packages.

  1. Install poetry:

    $ curl -sSL https://install.python-poetry.org | python3 -

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

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

  3. Install system dependencies via apt install:

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

  4. Install LedFx and its requirements using poetry:

    $ cd LedFx
$ poetry install

  5. This will let you run LedFx directly from your local copy via:

    $ poetry run ledfx --open-ui

macOS

  1. Install poetry:

    $ curl -sSL https://install.python-poetry.org | python3 -

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

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

  3. Install LedFx and its requirements using poetry:

    $ cd LedFx
$ poetry install

  4. This will let you run LedFx directly from your local copy via:

    $ poetry run 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 pnpm as the core package management.

Note

The following instructions assume you have already followed the steps above to install the LedFx dev environment and have the backend running. If you have not done so, please do so before continuing.

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)

Windows

1. Install Node.js and pnpm:

First, you need to install Node.js. You can download it from Node.js official website. After installing Node.js, you can install pnpm via npm (which is installed with Node.js).

$ npm install -g pnpm

2. Navigate to the frontend directory and install the dependencies:

$ cd frontend
$ pnpm install

3. Start LedFx in developer mode and start the pnpm watcher:

$ poetry shell ledfx
$ pnpm start

At this point, any changes 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.

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

$ pnpm build

Linux

1. Install Node.js:

Node.js is a prerequisite for pnpm. You can install it using your distribution’s package manager. For Ubuntu, you can use the following commands:

$ sudo apt-get update
$ sudo apt-get install nodejs

2. Install pnpm:

$ curl -fsSL https://get.pnpm.io/install.sh | sh -

3. Navigate to the frontend directory and install the dependencies:

$ cd frontend
$ pnpm install

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.

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

$ poetry shell ledfx
$ pnpm 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.

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

$ pnpm build

macOS

1. Install nodejs and NPM requirements using homebrew:

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

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

$ poetry shell ledfx
$ pnpm start

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

$ pnpm 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