Compile in Qt Creator

Summary

1. Prerequisites
2. Change default settings
   1. Build folder
   2. Install folder
3. Open the project
   1. Configure the project
   2. View the source code
4. Change project settings
   1. Build settings
   2. Run settings
5. Start debugging
   1. Compile
   2. Debug
6. 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 highly recommended for a more convenient development experience with MuseScore and other software projects.

Build folder

Justification

By default, Qt Creator creates build folders outside 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. Go to the Default build directory field. It will contain a value like:

   ../build-%{JS:Util.asciify("%{Kit:FileSystemName}-%{BuildConfig:Name}")}
   

4. Edit the value as follows:
   1. Remove ../ from the beginning.
   2. Change build- to builds/ (i.e. replace the first - with s/).

This will create build directories like builds/Desktop_Qt_6_9_0_MSVC2022_64bit-RelWithDebInfo/, into which all compiled or CMake-generated files will be placed.

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.

Install folder

Justification

CMake installs project files to CMAKE_INSTALL_PREFIX, which defaults to /usr/local on Linux and macOS, or C:/Program Files/${PROJECT_NAME} on Windows. However, this requires root or Administrator privileges, which is unsafe for developmental code. Also, it can clobber other installations, cause conflicts, and leave orphaned files that are difficult to remove.

Instead, we'll ask it to install files into a new subdirectory of the build folder called install, which avoids all of these problems. It also makes it possible to remove all traces of a build from your machine simply by deleting the build folder.

To change the default installation directory (i.e. CMAKE_INSTALL_PREFIX) in Qt Creator:

1. Go to Edit > Preferences > Kits.
2. Under the Kits tab, select one of the kits you have installed.
   • These usually 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
   

During configuration, Qt Creator will replace %{buildDir} with the actual path to the build folder. If you set the build folder as recommended above then CMake-installed files will 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 you install manually or 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 defined in this dialog apply to all configurations of the project, even if you delete your build directory and start again. Technically, the variables will be defined for all CMake projects you build in Qt Creator, not just MuseScore, but the MUSE or MUE prefix should prevent conflicts.

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 configuration type for it.

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

Learn about configuration types

The available configuration types (aka build types) are:

Type	Description
Debug	Special symbols are included in the compiled executable to enable advanced debugging techniques (e.g. to set breakpoints, pause the running application, step through code line-by-line, monitor the value of code variables, etc.). Most compiler optimizations are disabled, so the program may run slowly, but control flow in the machine code should correspond very closely to what you wrote in the C++ code. In Qt Creator, QML debugging is enabled by default in Debug builds, which has implications for security, but should be safe for development purposes as long as you're behind a firewall. You can disable it manually if you prefer. Failed assert() statements, including Muse's special IF_ASSERT_FAILED() macro, will deliberately crash Debug builds, 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, which creates a smaller executable that runs faster on end-users' machines. Control flow in the machine code may differ significantly from the C++ code (e.g. more functions may be inlined and more loops unwound), but the end result should be the same, albeit faster. In Qt Creator, QML debugging is disabled by default in Release builds for better performance and security, but you can enable it manually if you prefer. Normal assert() statements are ignored in Release builds, so there are no artificial crashes. Muse's special IF_ASSERT_FAILED() macro won't crash if the assertion fails, but it will print a warning on the console and execute the safety code enclosed in the subsequent {} brace 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.
RelWithDebInfo	A compromise between Release and Debug. Most Release optimizations are enabled, but most Debug symbols for C++ debugging are included. Assertions behave like in a Release build, so take care when adding new ones. By default, 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.
Profile	A special configuration that's unique to Qt Creator. It's like RelWithDebInfo except QML debugging is enabled by default. 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.
MinSizeRel	A release build with further optimizations applied that may sacrifice some performance in return for a smaller executable size.

Since you're 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 via CMake. You can follow its progress in the General Messages tab at the bottom of the Edit screen. The initial CMake run takes about 30 seconds to complete. If it fails, make sure you have properly completed all prerequisites.

About the initial CMake run

The initial CMake run is necessary for Qt Creator to understand the project structure in terms of CMake targets (i.e. MuseScore's modules and third-party dependencies), and to show a list of available CMake variables on the Build Settings page. You can't do much in Qt Creator until this run is complete, but it doesn't take long.

Tip

If the configuration fails, scroll up to find the very first error in the General Messages log. Ignore all subsequent errors because they may just be symptoms of the initial error. Fix the initial error, then redo the configuration and see if any other errors remain.

If you haven't edited any CMake files then a failure here probably means you need to install another dependency or change one of the CMake configuration variables. If you have edited a CMake file, the failure is likely due to a problem in that file. Problems in other files (e.g. C++ files) will not cause an error at this stage.

Note

As soon as CMake has finished running, Qt Creator will begin analysing the C++ code to build its internal Clang Code Model. While this is happening, you'll see a progress bar in the bottom right of the screen counting the number of files it has analysed so far. This can take a long time to complete, but it's done in the background so you can carry on using the program in the meantime, and even try to compile.

View the source code

The ☰ Edit screen in Qt Creator contains the Editor: a large blank area that will show source code once you've selected a source file from the tree (view) on the left.

Above the tree is a dropdown ↕️ that contains options like:

• Projects (default)
• Open Documents
• Bookmarks
• File System (recommended)
• Class View
• ...

The tree is confusing in the Projects view, so we recommend you choose the File System option instead. This will expose a second dropdown ↕️, which you should change to say MuseScore (i.e. the project name). Now you should see real files and folders in the tree.

About the other views

In the Projects view, the tree shows a folder called MuseScore [master], and within it, some of the folders in MuseScore's repository, like share, src, and vtest (basically, any folder that contains a CMakeLists.txt). However, many files and folders are missing from this view, and many of the "folders" that are shown are not really folders, but targets defined in MuseScore's CMake files, or groupings like "Headers" and "Sources" that Qt Creator has decided to lump together.

Note

Most C++ and QML code files are in the src folder. For example src/app/main.cpp contains the main() function, which is the entry point into the program.

Subfolders within src are for each of MuseScore's modules, such as engraving, inspector (i.e. the Properties panel), and importexport.

Warning

Don't make any changes to the code yet. Wait until after you've successfully compiled and run the program, otherwise you won't know whether any errors are ours or yours.

Change project settings

Once the initial configuration is complete, switch to the 🔧 Projects screen. (This is different to the Projects view mentioned above, which was on the ☰ Edit screen.)

In the 🔧 Projects screen, on the left are options to Manage Kits and change the Active Project.

Below those, the Build & Run section lists 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. Here are some you might want to change:

Configuration variable	Recommended value
CMAKE_INSTALL_PREFIX	%{buildDir}/install. It should have this value already if you changed the default 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 hard to debug them remotely.
MUSE_MODULE_MUSESAMPLER	OFF unless you need to test with MuseSounds specifically. If so, keep this ON and read the ⚠️ warning in the Debug section.
MUSE_COMPILE_USE_UNITY	Keep this ON or the build will likely fail simply because nobody compiles with it OFF, so it rarely gets tested. About unity builds 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.

If necessary, use the Filter box above the table to find the variable you need, then double-click on its value to edit it.

Tip

If you want changes to persist after a reconfiguration with initial parameters (or deleting your build folder), don't edit variables in the table. Instead, click the Kit Configuration button above the table, locate the CMake Configuration line and click Change. Write your definitions as explained earlier for CMAKE_INSTALL_PREFIX.

Run settings

Justification

By default, Qt Creator compiles the project but doesn't install it, so the resulting program lacks external resources. You'll notice the following problems in MuseScore if you try to run it in this state:

• No templates in the "Create from template" tab of the New Score dialog.
• No braille in the Braille panel.
• Crashes and failed assertions.

To avoid these problems, it's necessary to install the program, and tell Qt Creator how to run the fully installed program rather than the bare executable it just compiled.

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're working on Preferences and want to check 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

Compile

To compile the program, click the big green ▶️🪲 Start debugging button (large arrow with the small bug symbol) in the bottom left of the screen. While it's compiling, click the Compile Output tab at the bottom of the ☰ Edit screen to follow the build's progress.

About compilation times

The initial build takes around 10 minutes to complete, but it could be significantly faster or slower depending on your machine. Subsequent, incremental builds are much faster, because it only needs to compile the files that changed, plus any files that #include those files.

MuseScore's modular structure helps to speed up incremental builds by keeping the number of #includes to a minimum, and ensuring that most code changes are confined to each module's internal files, which are not #included in other modules.

Tip

If the build fails, scroll up to find the very first error in the Compile Output log. Ignore all subsequent errors because they may just be symptoms of the initial error. Fix the initial error, then try compiling again and see if other errors remain.

If you haven't edited any files then a failure here probably means you need to install another dependency or change one of the CMake configuration variables. If you have edited files, the failure was probably caused by an issue in the C++ code, or (less likely) in one of the CMake files.

Debug

If the build finishes successfully then MuseScore will launch automatically, and you'll be taken to the 🪲 Debug screen in Qt Creator.

Tip

Now you've done a successful build, you can launch MuseScore more quickly in the future via Qt Creator's Debug (menu) > Start Debugging > Start Debugging Without Deployment. This runs the program immediately without checking if it should be recompiled.

Obviously, if you edit the code you'll need to recompile to see the effects of those changes. You can do this with the green ▶️🪲 Start debugging button.

Warning

Debugging is not possible while the MuseSampler library is loaded in MuseScore, and you might have trouble getting MuseScore to quit cleanly.

About MuseSampler and debugging

MuseSampler is a shared library that's loaded dynamically by MuseScore to enable MuseSounds. It's installed in the background by MuseHub when you install at least one MuseSound. It's not provided with any debugging symbols.

You can check whether the library is loaded via MuseScore's Diagnostics menu (or Help > Diagnostics in stable releases, which aren't debuggable anyway) > MuseSampler > Check MuseSampler. If you don't see this option, or if it says MuseSampler wasn't detected, then you're OK to continue debugging.

If MuseSampler is detected, you need to:

1. Quit MuseScore and MuseHub.
   • If MuseScore won't quit the normal way, use the 🟥 Stop button in Qt Creator, possibly followed by Debug (menu) > Abort Debugging.
2. Delete or rename the MuseSampler library file (see commands below).
3. Relaunch MuseScore in Qt Creator.

Note: Next time you open MuseHub, it will silently download MuseSampler again if it's not found at the normal location.

# Linux
cd "${HOME}/.local/share/MuseSampler/lib"
mv libMuseSamplerCoreLib.so libMuseSamplerCoreLib.so.backup

# macOS
cd "${HOME}/Library/Application Support/MuseSampler/lib"
mv libMuseSamplerCoreLib.dylib libMuseSamplerCoreLib.dylib.backup

# Windows - Git Bash
cd "${LOCALAPPDATA}/MuseSampler/lib/"
mv MuseSamplerCoreLib.dll MuseSamplerCoreLib.dll.backup

# Windows - PowerShell
cd "$env:LOCALAPPDATA\MuseSampler\lib\"
mv MuseSamplerCoreLib.dll MuseSamplerCoreLib.dll.backup

: Windows - CMD
cd "%LOCALAPPDATA%\MuseSampler\lib\"
move MuseSamplerCoreLib.dll MuseSamplerCoreLib.dll.backup

Qt Creator's 🪲 Debug screen is similar to the ☰ Edit screen, but there's a new panel below the editor with options for the running application:

• ⏸️ Interrupt / Continue (i.e. pause/unpause the app)
• 🟥 Stop (i.e. terminate it)
• ↪️ Step Over / Step Into / Step Out of code statements line-by-line.

There's also a Locals panel in the top right. To see how this works, click immediately to the left of a line number in the editor to set a 🔴 breakpoint on that line. When the app reaches that line of code, it will pause execution, and the Locals panel should display the values of any variables defined at that point in the code.

Note

The Locals panel can't show values for all variables. Sometimes you have to print the value on the console:

LOGI() << "var is " << var;  // Remember to #include "log.h".

However, this involves recompiling, so it's better to use breakpoints and the Locals panel if you can.

Watch how variables change as you ↪️ Step Over, Step Into, and Step Out of code statements line-by-line. You can also click the Application Output tab at the bottom of the screen to view MuseScore's command line output and debug messages.

Press ⏸️ Continue to unpause the app. If the breakpoint is inside a while or for loop, or a function that gets called repeatedly, the app will pause there again and again until the loop finishes or you click on the 🔴 breakpoint to remove it.

Note

You can't interact with the app while it's paused. On some systems, you might not even be able to see the app window until you unpause it.

Tip

Sometimes it's unclear whether the app is paused, frozen, or properly crashed. The way to tell is via the ⏸️ Interrupt / Continue button in Qt Creator. If the tooltip for this button says "Interrupt" then the app is running but potentially frozen. If the tooltip says "Continue", you need to press the button to find out whether it's paused or crashed. If it's crashed, you won't be able to unpause it, and it might exit as soon as you press the button, or you might have to 🟥 Stop it, or even go to Debug (menu) > Abort Debugging.

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: