Getting Started with Source and Builds

This topic explains how to get the QGroundControl source code and build it either natively or within a Vagrant environment. It also provides information about optional or OS specific functionality.

Daily Builds

If you just want to test (and not debug) a recent build of QGroundControl you can use the Daily Build. Versions are provided for all platforms.

Source Code

Source code for QGroundControl is kept on GitHub. It is dual-licensed under Apache 2.0 and GPLv3.

To get the source files, clone the repo (or your fork):

git clone -j8 https://github.com/mavlink/qgroundcontrol.git

Build QGroundControl

Using Containers

We support Linux builds using a container found on the source tree of the repository, which can help you develop and deploy the QGC apps without having to install any of the requirements on your local environment.

Container Guide

Native Builds

QGroundControl builds are supported for macOS, Linux, Windows, and Android. Creating a version of QGC for iOS is theoretically possible but is no longer supported as a standard build. QGroundControl uses Qt as its cross-platform support library.

The required version of Qt is 6.11.1 (only).

WARNING

Do not use any other version of Qt! QGC has been thoroughly tested with the specified version of Qt (6.11.1). There is a significant risk that other Qt versions will inject bugs that affect stability and safety (even if QGC compiles).

For more information see: Qt 6 supported platform list.

Install Qt

You must install Qt as described below instead of using pre-built packages from say, a Linux distribution.

To install Qt:

1. Download and run the Qt Online Installer

   • Ubuntu:
     • Set the downloaded file to executable using: chmod +x.
     • It may also be necessary to install libxcb-cursor0.

2. On the Installation Folder page select "Custom Installation"

3. On the Select Components page:

• I you don't see Qt 6.11.1 listed check the Archive checkbox and click Filter.
• Under Qt -> Qt 6.11.1 select:
  • Windows: MSVC 2022 <arch> - where <arch> is the architecture of your machine
  • Mac: Desktop
  • Linux: Desktop gcc 64-bit
  • Android: Android
• Select all Additional Libraries
• Deselect QT Design Studio

1. Install Additional Packages (Platform Specific)

   Run these from the root of the cloned repository (cd qgroundcontrol):

   • Ubuntu: python3 tools/setup/install_dependencies --platform debian

   • Fedora: sudo dnf install speech-dispatcher SDL2-devel SDL2 systemd-devel patchelf

   • Arch Linux: pacman -Sy speech-dispatcher patchelf

   • Mac: python3 tools/setup/install_dependencies --platform macos

   • Windows: python tools/setup/install_dependencies --platform windows

     This is the same script used by CI. By default it installs only GStreamer (x64 only, from the QGC dependency mirror). Optional flags: --nsis installs NSIS (needed to build the installer), --msvc installs the Visual Studio 2022 Build Tools C++ workload, and --vulkan installs the Vulkan SDK.

   • Android: Installing dependencies for Android is quite involved. You are better off using Qt documentation for Android setup instructions. Read Qt 6 for Android carefully. Continue with Getting Started with Qt 6 for Android.

2. Install OS-Specific Functionalities

   INFO

   QGC is built exclusively with CMake; qmake builds are no longer supported. Optional features that are dependent on the operating system and user-installed libraries are linked/described below. These features can be forcibly enabled/disabled by passing additional -D options to CMake (e.g. -DQGC_ENABLE_GST_VIDEOSTREAMING=OFF).

   • Video Streaming/GStreamer: - installed by the dependency script above, or downloaded automatically at CMake configure time on Windows/macOS if not already present. See Video Streaming for details. Note: when cross-compiling for Windows ARM64 from an x64 host, disable video streaming with -DQGC_ENABLE_GST_VIDEOSTREAMING=OFF (this is what CI does) — the ARM64 GStreamer SDK installer cannot run on an x64 host, so the automatic download will fail.
   • Windows Installer: - building the Windows installer requires NSIS, which the dependency script above installs when run with --nsis.

Install Visual Studio Compiler (Windows Only)

An MSVC 2022 C++ toolchain is required. Either of the following works:

• The Visual Studio 2022 Build Tools with the C++ build tools workload (this is what CI uses, and what the dependency script above installs when run with --msvc), or

• Visual Studio 2022 Community Edition with the Desktop development with C++ workload, if you also want the IDE.

  INFO

  Visual Studio is ONLY used to get the compiler. Building QGroundControl is done using Qt Creator or cmake directly as outlined below.

Building using Qt Creator

1. Launch Qt Creator, select Open Project and select the CMakeLists.txt file.

2. On the Configure Project page it should default to the version of Qt you just installed using the instruction above. If not select that kit from the list and click Configure Project.

   TIP

   Don't forget to check boxes in case you want to build a Release instead of Debug, or check the other types. To create the installation file go to the "Deploy Settings" Tab, click in the menu button "Add Deploy Step", select "CMake Install" and as argument you must set at least --config Release.

3. Build using the "hammer" icon. After that, in order to deploy the build, use the "play" icon. Or use the menu Build on top for a detailed alternative.

Build using CMake on CLI

Example commands to build a default QGC and run it afterwards:

1. Make sure you cloned the repository before, see chapter Source Code above and switch into the repository folder:

   cd qgroundcontrol

2. Configure:

   ~/Qt/{{ $frontmatter.qt_version }}/gcc_64/bin/qt-cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug

   Change the directory for qt-cmake to match your install location for Qt and the kit you want to use.

   Windows: use the corresponding kit path, e.g. C:\Qt\6.11.1\msvc2022_64\bin\qt-cmake.bat, from a x64 Native Tools Command Prompt for VS 2022.

   Mac: To Sign/Notarize/Staple the QGC app bundle, add -DQGC_MACOS_SIGN_WITH_IDENTITY=ON to the configure command line. During the install phase the following environment variables will need to be available:

   • QGC_MACOS_SIGNING_IDENTITY - Signing identity for your Developer ID certificate which must be in the keychain
   • QGC_MACOS_NOTARIZATION_USERNAME - Username for your Apple Developer Account
   • QGC_MACOS_NOTARIZATION_PASSWORD - App specific password for Notarization from your Apple Developer Account
   • QGC_MACOS_NOTARIZATION_TEAM_ID - Apple Developer Account Team ID

3. Build

   cmake --build build --config Debug

4. Run the QGroundcontrol binary that was just built:

   ./build/Debug/QGroundControl

   On Windows: build\Debug\QGroundControl.exe

Vagrant

Vagrant can be used to build and run QGroundControl within a Linux virtual machine (the build can also be run on the host machine if it is compatible).

1. Download and Install Vagrant
2. From the root directory of the QGroundControl repository run vagrant up
3. To use the graphical environment run vagrant reload

Additional Build Notes for all Supported OS

• Parallel builds: You can use the -j# option with cmake --build to control the number of parallel build jobs.
• If you get this error when running QGroundControl: /usr/lib/x86_64-linux-gnu/libstdc++.so.6: version 'GLIBCXX_3.4.20' not found., you need to either update to the latest gcc, or install the latest libstdc++.6 using: sudo apt-get install libstdc++6.
• Unit tests: To run the unit tests, build in debug mode with QGC_UNITTEST_BUILD definition, and then copy deploy/qgroundcontrol-start.sh script into the debug directory before running the tests.

Build Caching

QGC uses two build caches, both enabled automatically at configure time and stored in the source tree so they survive build directory deletion:

• ccache caches compiler output (.ccache/). Used if ccache is installed and on your PATH.
• moccache caches Qt moc output (.cache/moccache/). QGC has a large number of moc-processed headers, so on clean builds, branch switches, and rebuilds after deleting the build directory a warm moccache skips the entire moc phase. Controlled by the QGC_USE_MOCCACHE CMake option (ON by default; not supported on Windows).

Neither cache requires any setup. To bypass moccache for a single build set MOCCACHE_DISABLE=1, or configure with -DQGC_USE_MOCCACHE=OFF to turn it off entirely.

moccache Details

moccache (tools/moccache.py) is a content-addressed cache wired in automatically as the CMAKE_AUTOMOC_EXECUTABLE via a launcher script generated at configure time. Cached moc output is keyed on moc version + arguments + input content + transitive include contents + the input's path relative to the output directory (moc embeds that relative path as an #include in its output, so build trees laid out at a different depth intentionally don't share entries). Entries are otherwise shared across build trees: build-dir paths are rewritten to a token, like ccache's base_dir.

Cache misses fall through to the real moc and never fail the build; corrupt or stale entries are re-validated by content hash on every use.

Environment variables (set by the launcher, overridable at build time):

Variable	Default	Purpose
MOCCACHE_DIR	<repo>/.cache/moccache	Cache location (persisted by CI, like ccache)
MOCCACHE_MAX_SIZE	256M	LRU auto-trim threshold (trims after misses)
MOCCACHE_DISABLE	unset	Pass through to real moc (no caching)
MOCCACHE_STATS	unset	Append hit/miss lines to $MOCCACHE_DIR/stats.log

MOCCACHE_STATS=1 just build                             # Log hits/misses during a build
python3 ./tools/moccache.py --trim --max-size 256M      # Explicitly trim the cache (LRU)
MOCCACHE_DISABLE=1 just build                           # Bypass the cache for one build

Building QGC Installation Files

You can additionally create installation file(s) for QGroundControl as part of the normal build process.

cmake --install build --config Release

Use the same build directory you passed to -B when configuring, and a configuration (Release/Debug) that you actually built.

On Windows this creates the NSIS installer (requires NSIS, installed by the dependency script when run with --nsis).