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. Replace the Default build directory text with builds/%{JS: Util.asciify("%{Kit:FileSystemName}-%{BuildConfig:Name}")}.
   • This will create build directories named like builds/Desktop_Qt_5_15_2_MSVC2019_64bit-Debug.

The builds folder is mentioned in MuseScore's .gitignore, which is necessary to prevent the files in this folder being tracked by Git or searched by ripgrep. For other software projects, you'll need to add /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 is not 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 most likely 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.
4. In the dialog that appears, add a new definition line: -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.
5. Repeat steps 2–4 for your other kits, if there are any.
   • If you install new kits in the future via Qt's Maintenance Tool then you'll have to repeat it for those as well.

Now files will be installed into folders named like builds/Desktop_Qt_5_15_2_MSVC2019_64bit-Debug/install, assuming you set the default build directory as recommended above.

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.

Pick any build kit and enable at least one build configuration for it. 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.).
Release	All debug symbols are removed to create a smaller executable that runs faster on end-users' machines.
RelWithDebInfo	A compromise between Release and Debug that includes some symbols for limited debugging. 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.
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 to use Debug or RelWithDebInfo. If in doubt, choose RelWithDebInfo.

Tip: If you want to work on the Release configuration for deployment to end-users then you should compile on the command line using the same method as the CI scripts.

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.
MUE_BUILD_UNIT_TESTS	ON 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.
MUE_COMPILE_USE_UNITY	At this moment, ignore this option and leave it ON; when it is turned OFF, the build currently fails. OFF. Unity builds are faster for the initial build but slower for subsequent, incremental builds. Also, Qt Creator's internal C++ model is broken for unity builds, so you wouldn't be able to use advanced IDE features like "Find references to this symbol".

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 > CMake Build.
2. Next to Targets, ensure 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 (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}

Start debugging

To compile the program, click the large green arrow with the 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: