Compile in Qt Creator - musescore/MuseScore GitHub Wiki

1. Prerequisites
2. Change default settings
   1. Build folder
   2. Install folder
3. Open the project
   1. Configure the project
   2. View the source tree
4. Change project settings
   1. Build settings
   2. Deploy settings
   3. 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. Our internal team uses Qt Creator, so you'll find it's better supported than other IDEs.

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.

These changes will affect all software projects you build in Qt Creator, not just MuseScore.

To change the default build directory in Qt Creator:

1. Go to 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 to be more like:

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

   The exact changes are:
   1. Remove ../ from the beginning.
   2. Change build- to builds/ (i.e. replace the first - with s/).

This creates build directories like builds/Qt_6_10_1_for_macOS-Debug/ to hold all compiled or CMake-generated files.

To change the default installation directory in Qt Creator:

1. Go to Preferences > Kits.
2. In the Kits tab, select one of the available desktop kits.
   • These usually appear under the "Auto-detected" heading. You may only have one.
   • It will look like 🖥️ Desktop Qt <version> <compiler> or 🖥️ Qt <version> for macOS.
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

   Before it passes this definition to CMake, Qt Creator automatically expands the %{buildDir} parameter into the actual build folder path, which makes CMake install to folders like builds/Qt_6_10_1_for_macOS-Debug/install/.
5. Optionally add more lines for other CMake variables you want to define in this dialog:

   -DMUSE_ENABLE_UNIT_TESTS:BOOL=OFF   # Linux & macOS: Keep this ON. Tests are only broken on Windows.
   -DMUSE_MODULE_MUSESAMPLER:BOOL=OFF  # Debugging RelWithDebInfo builds isn't possible with this ON.

   Variables defined here are preserved even if you delete your build directory and start again. Technically, these variables are defined for all projects, not just MuseScore, but the MUSE prefix is there to prevent conflicts.
6. Repeat steps 2–5 for your other kits, if you have any.
   • If you install another kit in the future, either manually or via Qt's Maintenance Tool, you'll need to repeat these steps for that kit as well.

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.

You'll be asked to choose a build kit, which means the Qt prebuilt component you installed earlier. It looks like:

• macOS: 🖥️ Qt <version> for macOS
• Windows & Linux: 🖥️ Desktop Qt <version> <compiler>

Select a kit and enable at least one configuration type for it, such as:

• Release with Debug Information (aka RelWithDebInfo). This is the best option for most developers!
• Debug. This is the best option on very powerful machines, such as Apple Silicon Macs.

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.

# Example command to run in MuseScore's source directory:
rm -rf builds/Qt_6_10_1_for_macOS-Debug  # Or whatever your build directory is called.

On the ☰ Edit screen in Qt Creator, go to the tree of files and folders in the left sidebar.

Immediately above the tree should be a dropdown ↕️ containing view options like:

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

Switch to the File System view. This reveals a second dropdown ↕️, which you should change to say MuseScore (i.e. the project name). Now the tree should show all the files and folders in MuseScore's repository.

After 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.)

On the 🔧 Projects screen, select your kit in the left sidebar and go to:

• Qt Creator v18+: The Build Settings tab.
• Older versions: The 🔨 Build page.

Here you should see options to set the current project's:

• CMake variables
• Build steps
• Environment variables

If you followed our earlier recommendation to change the default installation folder then you don't need to do anything here. For now, continue straight to Deploy Settings. You can return to this section later if you need to.

On the 🔧 Projects screen, select your kit in the left sidebar and go to:

• Qt Creator v18+: The Deploy Settings tab.
• Older versions: The ▶ Run page, Deployment section.

Here:

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

On the 🔧 Projects screen, select your kit in the left sidebar and go to:

• Qt Creator v18+: The Run Settings tab.
• Older versions: The ▶ Run page, Run section.

Here you should find a dropdown labelled Active run configuration (or just Run configuration). This dropdown contains the names of executable targets declared in the CMake files, such as MuseScoreStudio and (if the unit tests are enabled) braille_tests, engraving_tests, and iex_musicxml_tests, etc.

Naturally, the MuseScoreStudio configuration runs the app itself, but not the deployed version, hence it's necessary to:

1. Click Add... next to the run configuration dropdown.
2. Choose Custom Executable and click Create.
3. Click Rename, enter MuseScore Studio (installed) as the new name, and click OK.
4. Enter the following in the fields below:
   • 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 its 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 successfully but fails to run afterwards, 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.

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

# Example command to run in MuseScore's source directory:
rm -rf builds/Qt_6_10_1_for_macOS-Debug  # Or whatever your build directory is called.

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

# 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.

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

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.

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: