Compile in Qt Creator

Summary

1. Prerequisites
2. Change default settings
   1. Build directory
   2. CMAKE_INSTALL_PREFIX
3. Open the project
4. Configure the project
5. Change project settings
   1. Build settings
   2. Run settings
6. Start debugging
7. Common issues
   1. macOS asks "MuseScore would like to access files in your Desktop folder" too often

Qt Creator is a cross-platform IDE (integrated development environment) that comes with Qt and is specifically designed for building Qt software.

It's recommended that all developers use Qt Creator to compile MuseScore. The internal team uses Qt Creator, so you'll find it's better supported than other IDEs.

Prerequisites

You should have already completed the required steps in:

1. Set up developer environment
2. Install Qt and Qt Creator
3. Get MuseScore's source code
4. Install dependencies

If you're a new developer, you should learn how to compile on the command line before you attempt to set up an IDE.

Change default settings

These changes are optional but recommended for a more convenient development experience with MuseScore and other software projects.

Build directory

By default, Qt Creator creates build directories outside of the source folder, which isn't very tidy. Instead, we'll ask it to create builds in a new subdirectory of the source folder called builds.

To change the default build directory in Qt Creator:

1. Go to Edit > Preferences > Build & Run.
2. Open the Default Build Properties tab.
3. The Default build directory will look something like ../build-%{JS: Util.asciify("%{Kit:FileSystemName}-%{BuildConfig:Name}")}.
   • Remove ../ from the beginning and change build- to builds/ to put new builds in a subdirectory of the source folder.
   • This will create build directories named like builds/Desktop_Qt_6_9_0_MSVC2022_64bit-RelWithDebInfo/.

Note

The builds folder is mentioned in MuseScore's .gitignore, which is necessary to prevent the files in this folder being tracked by Git and searched by ripgrep.

Tip

If you compile other software projects in Qt Creator, consider adding /builds to that project's .gitignore file, or your personal ignore file at .git/info/exclude.

CMAKE_INSTALL_PREFIX

By default, CMake installs files to /usr/local on Linux and macOS, or C:\Program Files on Windows. However, installing to these locations requires root or Administrator privileges, which isn't safe for developmental code. Instead, we'll ask it to install files to a new subdirectory of the build folder called install.

To change the default value of CMAKE_INSTALL_PREFIX in Qt Creator:

1. Go to Edit > Preferences > Kits.
2. In the Kits tab, select one of the kits you have installed.
   • These will appear under the "Auto-detected" heading with names like Desktop Qt <version> <compiler>. You may only have one.
3. At the bottom of the Kits tab, locate CMake Configuration and click Change.
   • This opens the Edit CMake Configuration dialog for your chosen kit.
4. In this dialog, add a new definition line below the others:

   -DCMAKE_INSTALL_PREFIX:FILEPATH=%{buildDir}/install
   

   • When building a project, Qt Creator will replace %{buildDir} with the actual path to that project's build directory.
   • Using the example above, installed files would appear in builds/Desktop_Qt_6_9_0_MSVC2022_64bit-RelWithDebInfo/install/.

Note

You'll need to repeat steps 2–4 for your other kits, if you have any, as well as for any future kits that you install via Qt's Maintenance Tool.

Tip

You can define more variables in the Edit CMake Configuration dialog, such as -DMUSE_ENABLE_UNIT_TESTS:BOOL=OFF to disable unit tests (see below for ideas). Variables set in this dialog apply to all projects in Qt Creator, not just MuseScore, but most projects will ignore variables that they're not expecting, and the MUSE or MUE prefix helps to avoid conflicts. The advantage of defining variables here is that they won't disappear when you reconfigure CMake with initial parameters (e.g. if you delete your build folder to do a clean build, or you add another configuration).

Open the project

Inside Qt Creator's Welcome screen or File menu, use the option to open an existing project. (Don't use the option to create a new project.)

Open the CMakeLists.txt file in the root of MuseScore's code directory.

Configure the project

You'll be asked to choose a build kit. You have one build kit for each version and compiler of Qt you have installed.

Example kit: Desktop Qt 6.9.0 MSVC2022 64bit

Pick any build kit and enable at least one build configuration for it.

Example configuration: Release with Debug Information (aka RelWithDebInfo). This is a good option for most developers.

Learn about build configurations

The available configurations are:

Configuration	Description
Debug	Special symbols are included in the compiled executable to enable advanced debugging techniques (e.g. set breakpoints, pause the running application, step through code line-by-line, monitor the value of code variables, etc.). QML debugging is also enabled, which has security implications, but should be safe for development purposes as long as you're behind a firewall. Failed assert() statements, including MuseScore's special IF_ASSERT_FAILED() macro, will deliberately crash the program, thereby forcing you to fix the faulty logic that led to the failed assertion.
Release	All debugging symbols are removed, and most compiler optimizations are enabled, to create a smaller executable that runs faster on end-users' machines. QML debugging is disabled for better performance and security. Normal assert() statements are ignored and MuseScore's special IF_ASSERT_FAILED() macro won't crash if the assertion fails, but it will execute the safety code enclosed in the subsequent {} block. Tip: If you're compiling in Release mode, you should think carefully before adding any new assert() or IF_ASSERT_FAILED() statements. They won't crash for you, but they might crash for other developers.
Profile	A compromise between Release and Debug that is optimized but includes some symbols for C++ and QML debugging. assert() and IF_ASSERT_FAILED() behave like in a Release build, so take care when using these statements. Tip: Use this option if you find that MuseScore runs slowly when compiled in the Debug configuration, which can occur even on fast machines due to the large size and complexity of the codebase.
RelWithDebInfo	Similar to Profile except QML debugging is disabled, so only C++ debugging is possible. Tip: Use this option on Windows if you can't get the program to launch in the Profile configuration.
MinSizeRel	A release build with further optimizations applied that may sacrifice some performance in return for a smaller executable size.

As a developer using an IDE, it only really makes sense for you to use Debug, Profile, or RelWithDebInfo. If in doubt, choose RelWithDebInfo.

Once you've made a selection, Qt Creator will perform the initial configuration. If it fails, check you have properly completed all prerequisites.

Change project settings

Once the initial configuration is complete, switch to the Projects screen. The Build & Run section on the left should list available build kits.

Enabled kits look like this:

• 🖥️ Desktop Qt [version] [compiler]
  • 🔨 Build
  • ▶ Run

Build settings

From the Projects screen, click Build under your chosen kit. This takes you to the Build Settings page for that kit.

In the CMake section on the right, select the Current Configuration tab. You'll see a table of CMake variables listed as Key, Value pairs.

We recommend editing the following variables:

Configuration variable	Recommended value
CMAKE_INSTALL_PREFIX	%{buildDir}/install. It should have this value already if you changed the default setting as recommended earlier.
MUSE_ENABLE_UNIT_TESTS	OFF on Windows (and macOS?) because the tests are broken there anyway. ON on Linux so you can run unit tests locally. Set to OFF for a faster initial build, but if the tests fail (or fail to compile) on GitHub Actions, it's a pain to debug them remotely.
MUSE_COMPILE_USE_UNITY	Keep this ON or the build will likely fail simply because nobody compiles with it OFF, so it never gets tested. Unity builds are faster for the initial build but can be slower for subsequent, incremental builds. Also, IDEs sometimes struggle to understand the code layout of unity builds, although this may be due to configuration problems (i.e. user error). In Qt Creator, if you open a file and see a yellow warning "This file is not part of any project", it may be because of this.

Type a variable's key (i.e. name) in the Filter box to find it in the table, then double-click on its value to edit it. If the variable you want isn't there, use the Add button to create a new variable with the required name. The Batch Edit option is also useful.

Hint: Changes made here apply to the current configuration only, so you'll need to repeat these changes if you create a new configuration or re-configure the project with initial parameters.

Run settings

By default, Qt Creator compiles the project but doesn't install it, so the resulting program lacks external resources such as fonts, sounds, and score templates for the New Score dialog. If you want access to these things (recommended) then it's necessary to install the program.

From the Projects screen, click Run under your chosen kit. This takes you to the Run Settings page for that kit.

In the Deployment section on the right:

1. Click Add Deploy Step.
2. Choose CMake Install.
   • If you don't see CMake Install, choose CMake Build and then make sure the install target is selected.

In the Run section:

1. Find Run configuration and click Add....
2. Choose Custom Executable and click Create.
3. Click Rename and type "MuseScore Studio (installed)" as the new name.
4. Click OK and enter the following information:
   • Executable:
     • Linux: %{buildDir}/install/bin/mscore
     • macOS: %{buildDir}/install/mscore.app/Contents/MacOS/mscore
     • Windows: %{buildDir}/install/bin/MuseScore4.exe
   • Command line arguments:
     • Leave blank or add any valid arguments. We recommend using -F for development so you always see the program in it's initial state. Remove this option if you are working on Preferences and want to test that your changes are persistent.
   • Working directory:
     • %{sourceDir}

In the Environment section:

1. Click the Details button to the right to see environment variables and their values.
2. For the Base Environment, choose Build Environment.
3. If MuseScore compiles but fails to run, try adding this in the empty box to the right of the variables:

   PATH=+${QTDIR}/bin

   This appears to be necessary if you're building with Qt 6.9+ on Windows.

Start debugging

To compile the program, click the large green arrow with the small bug symbol ▶️🪲 in the bottom left of the screen. Click the Compile Output tab at the bottom of the screen to follow the progress of the build and check for errors if it fails.

If the code compiles successfully then MuseScore will launch automatically as soon as the build is complete. Click the Application Output tab at the bottom of the screen to view MuseScore's command line output and debug messages.

Common issues

macOS asks "MuseScore would like to access files in your Desktop folder" too often

Every time that you have compiled MuseScore, macOS should ask this one time (one time per folder: Desktop, Documents, Downloads). But on Apple Silicon Macs, the security is a bit more strict; this causes macOS to ask permission again and again, for every single operation MuseScore does with the file system. So, also when loading the list of recent files, macOS will ask it for each recent file again. This is annoying and not workable. The solution is to codesign the compiled MuseScore app. That means running the following command:

codesign --force --deep --sign - /path/to/install/directory/mscore.app

where /path/to/install/directory is the path specified in CMAKE_INSTALL_PREFIX.

In Qt Creator, this can be done too:

1. Go to Projects mode
2. Go to "Run"
3. Under Deployment, click "Add Deploy Step" and then "Custom Process Step"
4. Enter the following information:
   • Command: codesign
   • Arguments: --force --deep --sign - /path/to/install/directory/mscore.app where /path/to/install/directory is the path specified in CMAKE_INSTALL_PREFIX.
   • (Working directory does not matter.)

If the install directory is /Users/casper/Desktop/MuseScore/MuseScore4_Qt6.install, then the result should look like this: