How To Set up QtCreator for ArmarX

Using Axii (Recommended)

Axii provides modules for different versions of QtCreator. These modules configure QtCreator correctly to work well with ArmarX workspaces.

Note
For tools such as IDEs, it is recommended to create a separate ArmarX workspace. See Axii's documentation (Tools Integration) for instructions.

To install QtCreator, add the respective module and run an upgrade:

On Ubuntu 18:

axii workspace add tools/qtcreator/5.0
axii workspace upgrade -m tools/qtcreator/5.0

On Ubuntu 22:

axii workspace add tools/qtcreator/10.0
axii workspace upgrade -m tools/qtcreator/10.0

Using the Official Installer

Note
Using flatpak to install QtCreator is not recommended. The flatpak installation of QtCreator may not optimally use / interact with the system environment. If in doubt, install via the official installer (see instructions below).

Install QtCreator

  • Download the Qt Online Installer from here. The downloaded file should be called qt-creator-opensource-linux-x86_64-5.0.3.run.
  • Move the installer to a suitable directory, e.g. ~/opt/qtcreator/
$ mkdir -p ~/opt/qtcreator
$ cd ~/opt/qtcreator
$ mv ~/Downloads/qt-creator-opensource-linux-x86_64-5.0.3.run .
  • Execute the installer:
$ chmod u+x qt-creator-opensource-linux-x86_64-5.0.3.run
$ ./qt-creator-opensource-linux-x86_64-5.0.3.run
  • In the installer, you first have to enter some account credentials. If you don't want to create an account, ask your supervisor. Then, press Next.
  • Read the license obligations, then check the two boxes "I have read and approve the obligations of using Open Source Qt" and "I am an individual person not using Qt for any company. Then, press Next.
  • In the next screen, you will be told that there is no commercial license available in your Qt account. This is okay, you can continue with the Qt Open-Source installation. Press Next.
  • Specify the installation directory, e.g. ~/opt/qtcreator/qtcreator, then press Next.
  • Next, you can choose which components to install. There should only be the "Developer and Designer Tools", which are already selected. Press Next.
  • Again, read and accept the agreement, then press Next.
  • Finally, press Install.
  • Wait until installation is complete.

To map the command qtcreator to the new version, add this line to your ~/.bashrc:

export PATH="$HOME/opt/qtcreator/qtcreator/bin:$PATH"

Source your ~/.bashrc (source ~/.bashrc) or open a new terminal, then confirm that the new version is used:

$ which qtcreator
/.../opt/qtcreator/qtcreator/bin/qtcreator
$ qtcreator -version
Qt Creator 5.0.3 based on Qt 5.15.2
[...]

Start QtCreator

qtcreator

and proceed by configuring like explained below.

Configure QtCreator

You should edit some settings so they fit to our working setup and conventions.

Open the Settings via Tools > Options ... .

  • In the Kits section:
    • In the CMake tab:
      • Clone the System CMake at ...
      • Select the new entry, rename it to "ArmarX CMake", and press Make Default
      • Uncheck Autorun CMake
      • Set the path to the correct CMake installation
        • If you use Axii, set the path to $ARMARX_WORKSPACE/deps/cmake-3.21/cmake-3.21.3-linux-x86_64/bin/cmake and help file to $ARMARX_WORKSPACE/deps/cmake-3.21/cmake-3.21.3-linux-x86_64/doc/cmake/CMake.qch.
        • If you installed QtCreator via Flatpak, prepend the path by /run/host/ (e.g. /run/host/usr/bin/cmake)
        • If you [installed an up-to-date CMake without sudo](Update-CMake-(non-sudo)), set the path to .../cmake/bin/cmake and help file to .../cmake/doc/cmake/CMake.qch.
    • In the Kits tab:
      • Clone the Qt5 Kit
      • Select the new entry, rename it to "ArmarX" and press Make Default
      • Scroll down and set the CMake Tool to the newly created "ArmarX CMake"
      • Make sure a CMake Generator is configured. If not, press Change ..., select "Unix Makefiles" or "Ninja" as Generator, and press OK.
  • In the Text editor section:
    • In the Behavior tab:
      • Under Tabs And Indentation, set select Spaces Only and set Tab Size to 4
      • Under Mouse and Keyboard, uncheck Enable mouse navigation (having it enabled might interfere with Ctrl+C/Ctrl+V)
    • In the Display tab:
      • Check Display right margin at column and set the margin to 100
  • In the C++ section:
    • In the File Naming tab:
      • Check Use "pragma once" instead of "#ifndef" guards
      • Uncheck Lower case file names
  • In the Build & Run section:
    • In the General tab:
      • Check Save all files before build
    • In the Default Build Properties tab:
      • Set the Default build directory to build

Optional: Enable Autoformatting via Clang Format

Autoformatting in QtCreator via clang format requires three things:

  • An installation of clang
  • The Beautifier plugin in QtCreator
  • Clang format configuration files called .clang-format in the project directory or above

Clang format uses the .clang-format file in the project directory, or the closest .clang-format in the closest parent directory of the project. If no .clang-format exists in the project directory or any of its parent directories, no autoformatting will happen.

H²T-suggested Code Style Using Axii

The Axii module h2t/code_style contains and distributes different .clang-format files in the workspace. This module is added by default to every new workspace by Axii. Alternatively, you can add it to your workspace using axii add h2t/code_style.

Clang and Beautifier Plugin via Axii

When using the tools/qtcreator/... modules, clang and the Beautifier plugin for QtCreator are installed and configured automatically by Axii.

Clang and Beautifier Plugin: Manual Setup

Install clang-14

Check whether clang-14 is installed:

dpkg -V clang-14

If this prints nothing, clang-14 is installed. Otherwise, it will say ‘dpkg: package 'clang-14’ is not installed`.

Recommended: Install via axii

If clang-14 is not installed, install it by running (requires sudo):

axii workspace add tools/clang+llvm/14.0
axii workspace upgrade -m tools/clang+llvm/14.0

Deprecated: Manuall installation

For reference, it is also possible to do an installation without axii.

wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | sudo apt-key add -
echo 'deb http://apt.llvm.org/bionic/ llvm-toolchain-bionic-14 main' | sudo tee /etc/apt/sources.list.d/llvm.list >/dev/null
sudo apt update
sudo apt install -y clang-14 clang-format-14 clang-tidy-14 lldb-14 lld-14 clangd-14

Add the Beautifier Plugin to QtCreator

Enable the **_Beautifier_** Plugin in QtCreator:

  • In QtCreator, go to the Plugins menu via Help > About Plugins... .
  • Find Beautifier (under C++) and enable the plugin by ticking the check box.
  • Restart QtCreator.

In the settings of QtCreator (Tools > Options...), find the Beautifier section. There:

  • In the Clang Format tab, under Options:
    • If the Clang Format command is red, you might need to change it to clang-format-14 or supply a full path to the executable
    • Set Use predefined style to "File"
    • Set Fallback style to "None"
  • In the General tab:
    • (Optional) Check Enable auto format on file save and set Tool to "ClangFormat"
  • (Optional) Add a key shortcut to manually trigger the formatting when you see fit:
    • In the Environment section, go to the Keyboard tab.
    • Find and select the command "FormatFile" (without a space) under "ClangFormat".
    • Add a keybinding such as Alt+I.
    • You can also bind other commands, such as "DisableFormattingSelectedText", e.g. to Alt+Shift+I

Run Clang Format Manually from the Command Line

To manually clang-format all C++ files in a package or directory, you can do something like this:

for file in source/**/*.{h,cpp}; do
clang-format-14 $file -i
; done