Compile in Qt Creator

Summary

1. Change Qt Creator settings
   1. Default build directory
   2. Default CMAKE_INSTALL_PREFIX
2. Open the project
3. Configure the project
4. Change project install settings
   1. Edit build settings
   2. Edit run settings
5. Start debugging

You must have followed the steps to install Qt and Qt Creator and get MuseScore's source code. You are also encouraged to compile on the command line before you attempt to compile in Qt Creator or other IDEs.

Change Qt Creator settings

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

Default 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 file, which prevents it being tracked by Git or searched by ripgrep. For other projects, you'll need to add /builds to that project's .gitignore file or your personal ignore file at .git/info/exclude.

Default CMAKE_INSTALL_PREFIX

By default, CMake installs files to /usr/local on Linux and macOS, or to C:\Program Files on Windows. However, installing to these locations requires root or Administrator privileges, which is not safe for developmental code. Instead, we will install 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.
   • Qt Creator will expand %{buildDir} into the path to the build folder.
5. Repeat steps 2-4 for any other kits you have installed, and any new ones you install in the future via Qt's Maintenance Tool.

This will put installed files in folders named like builds/Desktop_Qt_5_15_2_MSVC2019_64bit-Debug/install, assuming you followed the change to default build directory we recommended above.

Open the project

Launch Qt Creator. From the File menu or Welcome screen, 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 will 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 options are:

Configuration	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.).
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 Debug builds are too slow on your machine.
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.

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 have made a selection, Qt Creator will begin performing the initial configuration. Note that if you did not follow the dependencies portion of getting the source code, QT will say you have a "cmake" error.

Change project install settings

By default, Qt Creator will compile the project but not install it. This gives you a program that basically works, but it will be missing certain features that rely on external resources such as fonts, sounds, and score templates for the New Score Wizard. If you want access to these things (recommended) then it is necessary to install the program.

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

Edit 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:

1. Select the Current Configuration tab.
2. Type "install" in the Filter box.
3. Locate the variable CMAKE_INSTALL_PREFIX. What value does it have?
   • If you followed our recommendation to change the default CMAKE_INSTALL_PREFIX then you should see that value here (i.e. %{buildDir}/install).
   • If you didn't follow our recommendation then you can change the value here, but note that the changes made here apply to the current configuration only, so you'll need to make the same change if you create a new configuration or re-configure the project with initial parameters.

Tip: Another variable you might want to change here is MUE_BUILD_UNIT_TESTS. See Fix the unit tests.

Edit run settings

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.
4. Type "MuseScore (installed)" as the new name and click OK.
5. 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.