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 here: https://github.com/mavlink/qgroundcontrol. It is dual-licensed under Apache 2.0 and GPLv3.

To get the source files:

1. Clone the repo (or your fork) including submodules:

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

2. Update submodules (required each time you pull new source code):

   git submodule update --recursive

TIP

Github source-code zip files cannot be used because these do not contain the appropriate submodule source code. You must use 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.10.1 (only).

WARNING

Do not use any other version of Qt! QGC has been thoroughly tested with the specified version of Qt (6.10.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.
     • You may also need 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.10.1 listed check the Archive checkbox and click Filter.

• Under Qt -> Qt 6.10.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)

   • Ubuntu: sudo bash ./qgroundcontrol/tools/setup/install-dependencies-debian.sh
   • Fedora: sudo dnf install speech-dispatcher SDL2-devel SDL2 systemd-devel patchelf
   • Arch Linux: pacman -Sy speech-dispatcher patchelf
   • Mac sh qgroundcontrol/tools/setup/install-dependencies-osx.sh
   • Windows qgroundcontrol/tools/setup/install-depedencies-windows.ps1
   • Android Installing dependencies for android is quite involved. You are better off using Qt documentation for android setup instructions. Search for "Qt 6.10 android" on the internet to find the correct "Gettting Started with Qt for Android" page. Read it full and carefully! An example of what you are looking for is here.

2. Install Optional/OS-Specific Functionality

   INFO

   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 specifying additional values to qmake.

   • Video Streaming/Gstreamer: - see Video Streaming

Install Visual Studio (Windows Only)

Install Visual Studio 2022 Community Edition.

When installing, select Desktop development with C++ as shown:

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.

3. Build using the "hammer" (or "play") icons or the menus:

   

Build using CMake on CLI

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

1. Make sure you cloned the repository and updated the submodules 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.

   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

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: For non Windows builds, you can use the -j# option to run parellel builds.
• 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.

Building QGC Installation Files

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

cmake --install . --config Release