Skip to content

chore: update Ubuntu 22.04 build environment script and docs #7209

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pfeerick merged 6 commits into from
Mar 24, 2026
Merged

chore: update Ubuntu 22.04 build environment script and docs #7209

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
b70ce56
tools: update Ubuntu 22.04 build environment script to match CI Docke…
pfeerick Mar 23, 2026
9df117f
fix: aqt installation location changed
pfeerick Mar 23, 2026
c576c10
tools: extract Qt and ARM toolchain versions as top-level constants
pfeerick Mar 23, 2026
6b125cd
tools: add Qt bin directory to PATH and improve quoting
pfeerick Mar 23, 2026
ee5de80
tools: create /opt/qt and set ownership before Qt installation
pfeerick Mar 23, 2026
9c1883a
docs: update Ubuntu 22.04 build instructions to reflect current tooling
pfeerick Mar 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 62 additions & 32 deletions docs/building/linux-ubuntu-22.04.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Build Instructions under Ubuntu 22.04

Last tested with Ubuntu 22.04.5 LTS in March 2026.

The document here is meant to help you develop or test changes to EdgeTX on your PC, not to build flight/radio safe version of binaries.

- [Setting up the build environment for EdgeTX](#setting-up-the-build-environment-for-edgetx)
Expand All @@ -8,7 +10,7 @@ The document here is meant to help you develop or test changes to EdgeTX on your

## Setting up the build environment for EdgeTX

You can setup Ubuntu 22.04 on bare-metal, inside a virtual machine environment, or using WSL2 under Windows 10. For WSL2 installation, please see a dedicated page about it: [Setting up Ubuntu 20.04 in a Windows Subsystem for Linux](linux-wsl.md).
You can setup Ubuntu 22.04 on bare-metal, inside a virtual machine environment, or using WSL2 under Windows 10/11. For WSL2 installation, please see a dedicated page about it: [Setting up Ubuntu in a Windows Subsystem for Linux](linux-wsl.md).

* Download [Ubuntu 22.04](https://ubuntu.com/download/desktop) and install it (using Minimal installation type is sufficient. Allow _Download updates while installing Ubuntu_. 3rd party software is not required, unless you need this for graphics or WiFi adapter on your PC).
* When the installer has finished and the obligatory reboot is done, log in. Install updates using Software Updater (click _Activities_ in top left corner, type in _Software Updater_ and press _Enter_). **Restart** the PC and log in again after reboot.
Expand All @@ -17,12 +19,12 @@ You can setup Ubuntu 22.04 on bare-metal, inside a virtual machine environment,
wget https://raw.githubusercontent.com/EdgeTX/edgetx/main/tools/setup_buildenv_ubuntu22.04.sh
```
```
chmod a+x setup_buildenv_ubuntu22.04.sh
chmod +x setup_buildenv_ubuntu22.04.sh
```
```
./setup_buildenv_ubuntu22.04.sh
```
* If all went smoothly, you should not have seen any errors.
* If all went smoothly, you should not have seen any errors, and should have been informed that setup was finished.

If you are interested to see what the script does or which functions it calls, you can open it in a text editor and have look at it - it's pretty self-explanatory (_gedit_ for example in Ubuntu is a text editor with syntax highlighting). You can alternatively start the script with _--pause_ argument to stop the script execution after each step to better inspect the output. To achieve this, issue `./setup_buildenv_ubuntu22.04.sh --pause` as the last command in the above list instead.

Expand All @@ -43,43 +45,45 @@ We will next fetch the EdgeTX source files from the GitHub main development bran
git clone --recursive -b main https://github.com/EdgeTX/edgetx.git edgetx_main
```
```
cd edgetx_main && mkdir build-output && cd build-output
cd edgetx_main && mkdir build-output
```

To build EdgeTX, we need to minimally specify the radio target, but can further select or de-select a number of build-time options. The following command will create a text-file list of all options for you to look at and saves it in current user home directory:
```
cmake -LAH ../ > ~/edgetx_main-cmake-options.txt
cmake -LAH -S . > ~/edgetx_main-cmake-options.txt
```

You can use, e.g. _gedit_ under Ubuntu to view the file.

As an example, we will build next for RadioMaster TX16S (PCB=X10, PCBREV=TX16S), mode 2 default stick (DEFAULT_MODE=2), global variables enabled (GVARS=YES), servo output unit as microseconds (PPM_UNIT=US), include Lua mixer script support (LUA_MIXER=YES) and selected the type as a Debug build with debug symbols included (CMAKE_BUILD_TYPE=Debug). The CMake command for this is (issue the following without line breaks and be sure to include at the end the two dots and a slash exactly as here listed):
As an example, we will build next for RadioMaster TX16S (PCB=X10, PCBREV=TX16S), mode 2 default stick (DEFAULT_MODE=2, will otherwise default to mode 1) and selected the type as a Debug build with debug symbols included (CMAKE_BUILD_TYPE=Debug). The CMake command for this is:
```
cmake -DPCB=X10 -DPCBREV=TX16S -DDEFAULT_MODE=2 -DGVARS=YES -DPPM_UNIT=US -DLUA_MIXER=YES -DCMAKE_BUILD_TYPE=Debug ../
cmake --fresh -S . -B build-output -Wno-dev -DPCB=X10 -DPCBREV=TX16S -DDEFAULT_MODE=2 -DCMAKE_BUILD_TYPE=Debug
```
If you do not want to include the debug symbols, use `-DCMAKE_BUILD_TYPE=Release` instead.

To build for other radios, you just need to select another build target by specifying appropriate values for `PCB` and `PCBREV` for your radio. If you are are wanting to build for multiple different targets, it is best to use a different build folder for each. Otherwise, delete the `CMakeCache.txt` file from the build directory before before running `cmake` to configure a different transmitter build, otherwise cached configuration values from your previous build target will cause weird compile results. As a tip, which values to use, have a look at a Python script according to your radio manufacturer in a file named `build-<radio-manufacturer>.py` under [https://github.com/EdgeTX/edgetx/tree/main/tools](https://github.com/EdgeTX/edgetx/tree/main/tools)
To build for other radios, you just need to select another build target by specifying appropriate values for `PCB` and `PCBREV` for your radio. It is best to use a different build folder for each target. As a tip for which values to use, have a look at a Python script according to your radio manufacturer in a file named `build-<radio-manufacturer>.py` under [https://github.com/EdgeTX/edgetx/tree/main/tools](https://github.com/EdgeTX/edgetx/tree/main/tools)

Starting with 2.8, an additional step is required. Issue:
It is recommended to set the `CMAKE_BUILD_PARALLEL_LEVEL` environment variable to the number of CPU cores on your system, to speed up all subsequent builds:
```
make configure
export CMAKE_BUILD_PARALLEL_LEVEL=$(nproc)
```
Alternatively, you can issue `make arm-none-eabi-configure` if you only want to build radio firmware or `make native-configure` if you only want to build targets meant to be run on computer (running `make configure` activates both architecture targets).

Only a few seconds later, you should be greeted with "-- Generating done" message.
To configure, issue:
```
cmake --build build-output --target arm-none-eabi-configure
```

The configure process generates the _makefile_ that is required in the next step to build the firmware. For this, issue:
To build the firmware, issue:
```
make -j`nproc` firmware
cmake --build build-output --target firmware --parallel
```
This process can take some minutes to complete (the parameter -j'nproc' instructs the make to use as many parallel threads as the current system has CPU cores. This speeds up the build quite significantly).
If successful, you should find a firmware binary _firmware.bin_ in the current folder, that you can flash into your radio.

It's a good idea to rename the binary, so that it is easier later to see the target radio and which options were baked into it. For this, issue in the build folder, e.g.:
This process can take some minutes to complete.
If successful, you should find a firmware binary _firmware.bin_ in the `build-output/arm-none-eabi` folder, that you can flash onto your radio.

It's a good idea to rename the binary, so that it is easier later to see the target radio and which options were baked into it. For this, issue e.g.:
```
cd arm-none-eabi
mv firmware.bin edgetx_main_tx16s_lua-ppmus-mode2_debug.bin
mv build-output/arm-none-eabi/firmware.bin edgetx_main_tx16s_mode2_debug.bin
```

You will need to prepare a clean microSD card and fill it with the content according to your radio type from [https://github.com/EdgeTX/edgetx-sdcard/releases/tag/latest](https://github.com/EdgeTX/edgetx-sdcard/releases/tag/latest)
Expand All @@ -91,31 +95,57 @@ You can use [EdgeTX Buddy](https://buddy.edgetx.org/), [EdgeTX Companion](https:

## Building Companion, Simulator and radio simulator libraries

To build radio simulator library, issue in the same terminal as opened previously:
### After EdgeTX 2.12

You can build firmware, the radio simulator module, Companion and Simulator all in one step:
```
make -j`nproc` libsimulator
cmake --build build-output --parallel --target firmware --target wasi-module --target companion --target simulator
```

From EdgeTX 2.10 onwards, Companion and Simulator only incorporate hardware definitions for radio simulated libraries built before they themselves are built.
This will configure and download extra dependencies as needed. Alternately, if you only want to build the simulator module at this point, you can run

In order to build for other radio target, you need to re-run the `cmake` line above, with other `PCB` and `PCBREV` tags.
```
cmake --build build-output --parallel --target wasi-module
```

The wasm simulator module is built into `build-output/wasm/wasm-build/` but Companion looks for it in `build-output/native/`. Copy it across before launching Companion or Simulator:
```
cp build-output/wasm/wasm-build/*.wasm build-output/native/
```

After building all required radio simulator libraries, build the EdgeTX Companion binary, issue in the same terminal as opened previously:
If you want to build simulator modules for multiple radio targets (so they are all available in Companion), the helper script `tools/build-wasm-modules.sh` can build all supported targets in one go:
```
make -j`nproc` companion
tools/build-wasm-modules.sh . ./wasm-modules/
```
To launch Companion, change into `native` directory and issue: `./companion<ver>`
where `<ver>` is EdgeTX version string in format of two digits. For example, for EdgeTX 2.9 use 29, thus `companion29`, for 2.10 `companion210` and so on.
The `.wasm` files are output to `./wasm-modules/`. Copy them to `build-output/native/` before building Companion.

To build EdgeTX Simulator binary, issue:
Change into the `native` directory, where `<ver>` is the EdgeTX version as digits (e.g. `212` for 2.12):
```
make -j`nproc` simulator
cd build-output/native
```

Before you run the simulator, copy the SD card content according to your radio target from [https://github.com/EdgeTX/edgetx-sdcard/releases/tag/latest](https://github.com/EdgeTX/edgetx-sdcard/releases/tag/latest) to your system and extract it e.g. to `~/edgetx/simu_sdcard/horus`
To launch Companion:
```
./companion<ver>
```

Also, you should create a radio profile first with `./companion<ver>`, before you can successfully run the full simulator.
Before running the simulator, copy the SD card content for your radio target from [https://github.com/EdgeTX/edgetx-sdcard/releases/tag/latest](https://github.com/EdgeTX/edgetx-sdcard/releases/tag/latest) and extract it e.g. to `~/edgetx/simu_sdcard/horus`. You should also create a radio profile first in Companion before running the simulator.

To launch the simulator, change into `native` directory and issue: `./simulator<ver>`. In the dialog that pops up, select _SD Path_ as data source and under _SD Image Path:_ browse to `~/edgetx/simu_sdcard/horus`
To launch the simulator:
```
./simulator<ver>
```
In the dialog that pops up, select _SD Path_ as data source and under _SD Image Path:_ browse to `~/edgetx/simu_sdcard/horus`

[![EdgeTX simulator on Linux](../assets/images/build/linux/EdgeTX_simulator_Linux.png)](../assets/images/build/linux/EdgeTX_simulator_Linux.png)

### Legacy: EdgeTX 2.10 to 2.12

From 2.10 onwards, Companion and Simulator only incorporate hardware definitions for radio simulator libraries built before they themselves are built. You need to build a `libsimulator` for each radio target you want to include.

To include additional radio targets, re-run the `cmake --fresh` configure command from above with different `PCB` and `PCBREV` values, then build `libsimulator` again for each **before** building Companion.

Build the radio simulator library for your target, then Companion and Simulator:
```
cmake --build build-output --parallel --target libsimulator --target companion --target simulator
```
133 changes: 59 additions & 74 deletions tools/setup_buildenv_ubuntu22.04.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,9 @@ set -e
## Bash script to setup EdgeTX development environment on Ubuntu 22.04 running on bare-metal or in a virtual machine.
## Let it run as normal user and when asked, give sudo credentials

QT_VERSION="6.9.3"
GCC_ARM_VERSION="14.2.rel1"

PAUSEAFTEREACHLINE="false"
STEP=1
# Parse argument(s)
Expand All @@ -21,14 +24,23 @@ if [[ $(lsb_release -rs) != "22.04" ]]; then
exit 1
fi

echo "=== Step $((STEP++)): Checking if i386 requirement is satisfied ==="
OUTPUT=x$(dpkg --print-foreign-architectures 2> /dev/null | grep i386) || :
if [ "$OUTPUT" != "xi386" ]; then
echo "Need to install i386 architecture first."
sudo dpkg --add-architecture i386
else
echo "i386 requirement satisfied!"
fi
echo "=== Step $((STEP++)): Setting up package repositories ==="
sudo apt-get -y install --no-install-recommends software-properties-common gpg gpg-agent wget ca-certificates
sudo mkdir -p /etc/apt/keyrings
# Set up Kitware repository for newer cmake
wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2>/dev/null | \
gpg --dearmor - | sudo tee /etc/apt/keyrings/kitware-archive-keyring.gpg >/dev/null
echo "deb [signed-by=/etc/apt/keyrings/kitware-archive-keyring.gpg] https://apt.kitware.com/ubuntu/ jammy main" | \
sudo tee /etc/apt/sources.list.d/kitware.list >/dev/null
# Set up NodeSource repository for Node.js 20.x
wget -O - https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key 2>/dev/null | \
gpg --dearmor - | sudo tee /etc/apt/keyrings/nodesource.gpg >/dev/null
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_20.x nodistro main" | \
sudo tee /etc/apt/sources.list.d/nodesource.list >/dev/null
# Set up Git PPA for newer git
sudo add-apt-repository ppa:git-core/ppa --yes
# Set up Rob Savoury's PPA for newer SDL2
sudo add-apt-repository ppa:savoury1/multimedia --yes
if [[ $PAUSEAFTEREACHLINE == "true" ]]; then
echo "Step finished. Please check the output above and press Enter to continue or Ctrl+C to stop."
read
Expand All @@ -42,95 +54,100 @@ if [[ $PAUSEAFTEREACHLINE == "true" ]]; then
fi

echo "=== Step $((STEP++)): Installing packages ==="
sudo apt-get -y install \
sudo apt-get -y install --no-install-recommends \
build-essential \
cmake \
gcc \
kitware-archive-keyring \
git \
lib32ncurses-dev \
lib32z1 \
libsdl2-dev \
software-properties-common \
wget \
zip \
python3-pip-whl \
python3-pil \
libgtest-dev \
unzip \
file \
gawk \
libsdl2-dev \
python3-dev \
python3-pip \
python3-tk \
python3-setuptools \
python3-tk \
libcups2 \
libssl-dev \
libgtest-dev \
clang \
python3-clang \
libusb-1.0-0-dev \
stlink-tools \
openocd \
npm \
pv \
libncurses5:i386 \
libpython2.7:i386 \
libclang-dev \
python-is-python3 \
openssl
dfu-util \
nodejs \
stlink-tools \
openocd \
pv
if [[ $PAUSEAFTEREACHLINE == "true" ]]; then
echo "Step finished. Please check the output above and press Enter to continue or Ctrl+C to stop."
read
fi

echo "=== Step $((STEP++)): Installing lv_font_conv ==="
sudo npm i lv_font_conv -g
if [[ $PAUSEAFTEREACHLINE == "true" ]]; then
echo "Step finished. Please check the output above and press Enter to continue or Ctrl+C to stop."
read
fi

echo "=== Step $((STEP++)): Installing Python packages ==="
sudo python3 -m pip install \
filelock \
asciitree \
jinja2 \
pillow==7.2.0 \
clang==14.0.0 \
future \
lxml \
pillow \
clang \
lz4 \
aqtinstall \
pyelftools
pyelftools \
pydantic
if [[ $PAUSEAFTEREACHLINE == "true" ]]; then
echo "Step finished. Please check the output above and press Enter to continue or Ctrl+C to stop."
read
fi

echo "=== Step $((STEP++)): Installing Qt ==="
./aqt install-qt --outputdir qt linux desktop 6.9.0 linux_gcc_64 -m qtmultimedia qtserialport
sudo mkdir -p /opt/qt
sudo chown "${USER}:${USER}" /opt/qt
aqt install-qt --outputdir /opt/qt linux desktop ${QT_VERSION} linux_gcc_64 -m qtmultimedia qtserialport
if [[ $PAUSEAFTEREACHLINE == "true" ]]; then
echo "Step finished. Please press Enter to continue or Ctrl+C to stop."
read
fi

echo "=== Step $((STEP++)): Fetching GNU Arm Embedded Toolchains ==="
# EdgeTX uses GNU Arm Embedded Toolchain version 14.2.rel1
wget -q --show-progress --progress=bar:force:noscroll https://developer.arm.com/-/media/Files/downloads/gnu/14.2.rel1/binrel/arm-gnu-toolchain-14.2.rel1-x86_64-arm-none-eabi.tar.xz
wget -q --show-progress --progress=bar:force:noscroll https://developer.arm.com/-/media/Files/downloads/gnu/${GCC_ARM_VERSION}/binrel/arm-gnu-toolchain-${GCC_ARM_VERSION}-x86_64-arm-none-eabi.tar.xz
if [[ $PAUSEAFTEREACHLINE == "true" ]]; then
echo "Step finished. Please press Enter to continue or Ctrl+C to stop."
read
fi

echo "=== Step $((STEP++)): Unpacking GNU Arm Embedded Toolchains ==="
pv arm-gnu-toolchain-14.2.rel1-x86_64-arm-none-eabi.tar.xz | tar xJf -
pv arm-gnu-toolchain-${GCC_ARM_VERSION}-x86_64-arm-none-eabi.tar.xz | tar xJf -
if [[ $PAUSEAFTEREACHLINE == "true" ]]; then
echo "Step finished. Please press Enter to continue or Ctrl+C to stop."
read
fi

echo "=== Step $((STEP++)): Removing the downloaded archives ==="
rm arm-gnu-toolchain-14.2.rel1-x86_64-arm-none-eabi.tar.xz
rm arm-gnu-toolchain-${GCC_ARM_VERSION}-x86_64-arm-none-eabi.tar.xz
if [[ $PAUSEAFTEREACHLINE == "true" ]]; then
echo "Step finished. Please press Enter to continue or Ctrl+C to stop."
read
fi

echo "=== Step $((STEP++)): Moving GNU Arm Embedded Toolchains to /opt ==="
sudo mv arm-gnu-toolchain-14.2.rel1-x86_64-arm-none-eabi /opt/gcc-arm-none-eabi
sudo mv arm-gnu-toolchain-${GCC_ARM_VERSION}-x86_64-arm-none-eabi /opt/gcc-arm-none-eabi
if [[ $PAUSEAFTEREACHLINE == "true" ]]; then
echo "Step finished. Please press Enter to continue or Ctrl+C to stop."
read
fi

echo "=== Step $((STEP++)): Adding GNU Arm Embedded Toolchain to PATH of current user ==="
echo 'export PATH="/opt/gcc-arm-none-eabi/bin:$PATH"' >> ~/.bashrc
echo "=== Step $((STEP++)): Adding GNU Arm Embedded Toolchain and Qt to PATH of current user ==="
cat >> ~/.bashrc << EOF
export PATH="/opt/gcc-arm-none-eabi/bin:\$PATH"
export PATH="/opt/qt/${QT_VERSION}/gcc_64/bin:\$PATH"
EOF
if [[ $PAUSEAFTEREACHLINE == "true" ]]; then
echo "Step finished. Please press Enter to continue or Ctrl+C to stop."
read
Expand All @@ -143,37 +160,5 @@ if [[ $PAUSEAFTEREACHLINE == "true" ]]; then
read
fi

echo "=== Step $((STEP++)): Fetching USB DFU host utility ==="
wget -q --show-progress --progress=bar:force:noscroll http://dfu-util.sourceforge.net/releases/dfu-util-0.11.tar.gz
if [[ $PAUSEAFTEREACHLINE == "true" ]]; then
echo "Step finished. Please check the output above and press Enter to continue or Ctrl+C to stop."
read
fi

echo "=== Step $((STEP++)): Unpacking USB DFU host utility ==="
pv dfu-util-0.11.tar.gz | tar xzf -
if [[ $PAUSEAFTEREACHLINE == "true" ]]; then
echo "Step finished. Please check the output above and press Enter to continue or Ctrl+C to stop."
read
fi

echo "=== Step $((STEP++)): Building and Installing USB DFU host utility ==="
cd dfu-util-0.11/
./configure
make
sudo make install
cd ..
if [[ $PAUSEAFTEREACHLINE == "true" ]]; then
echo "Step finished. Please check the output above and press Enter to continue or Ctrl+C to stop."
read
fi

echo "=== Step $((STEP++)): Removing the downloaded archive and build folder of USB DFU host utility ==="
rm dfu-util-0.11.tar.gz
rm -rf dfu-util-0.11
if [[ $PAUSEAFTEREACHLINE == "true" ]]; then
echo "Step finished."
fi

echo "Finished setting up EdgeTX development environment."
echo "Please execute: source ~/.bashrc"