Compile on the command line

Summary

1. Prerequisites
2. Running CMake manually (not recommended)
3. Using build.cmake (recommended)
   1. Locating Qt
   2. Passing options to CMake
4. Running the compiled program
   • Running with factory settings
5. What to do if the build fails
   • The configure step fails
   • The build step fails
   • The install step fails
   • MuseScore fails to run
   • Failures in general

Prerequisites

You must have followed the required steps in previous articles in this guide:

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

New contributors are encouraged to compile on the command line before they attempt to set up an IDE. This will help you learn how to distinguish general compilation errors, which would occur with any method of compilation, from errors that are specific to your IDE.

Running CMake manually (not recommended)

You could compile MuseScore like any other CMake program:

# Not recommended. Only do this if you know what you're doing.
cmake -S . -B my_build_dir [options]  # configure (first build only)
cmake --build my_build_dir            # build (every build)
cmake --install my_build_dir          # install (every successful build)

We don't recommend this because it requires effort to get working, and you have to remember all the options you passed to CMake in case you need to configure again at a later date. Instead, we provide the script build.cmake to do all of this for you.

Important information for multi-boot users: CMake and the native build tool process lots of files in a short amount of time. For best performance, always keep your source and build directories on a filesystem that is native to your operating system (NTFS for Windows, APFS for macOS, BTRFS or EXT4 for Linux). Failing to do this can lead to massively increased build times as well as other problems.

Using build.cmake (recommended)

We provide a script build.cmake to do the compilation for you. Call it like this on any platform:

# Recommended way to compile on any platform
cmake -P build.cmake  # configure, build, and install MuseScore 

Users of Unix-like systems (including Linux, macOS, and Git Bash on Windows) can use an even simpler form:

# Recommended way to compile on Unix-like platforms
./build.cmake  # configure, build, and install MuseScore 

Try running the build.cmake script. The build will fail, but don't worry; we'll try to fix this now.

Locating Qt

Skip this step if you are compiling within Qt Creator via a Custom Process Step. Qt Creator sets the QTDIR environment variable for you. It also adds the MinGW binary directory to PATH if you are using that compiler.

If you get an error about Qt not being found then you need to tell build.cmake where to find it. To do this, create a text file build_overrides.cmake in the root of the repository and use it to set the environment variable QTDIR to wherever Qt is located.

Tip: Advanced users can add conditional logic to build_overrides.cmake to load different versions of Qt depending on various factors, such as whether a certain option was passed to the build.cmake script on the command line. Study build.cmake to see how this kind of thing is done.

Linux

# build_overrides.cmake
set(ENV{QTDIR} "$ENV{HOME}/Qt/6.2.4/gcc_64") # or wherever Qt is located

macOS

# build_overrides.cmake
set(ENV{QTDIR} "$ENV{HOME}/Qt/6.2.4/macos") # or wherever Qt is located

Windows - MSVC

# build_overrides.cmake
set(ENV{QTDIR} "C:/Qt/6.2.4/msvc2019_64") # or wherever Qt is located

We use forward slashes (/) in the path because backward slash (\) is an escape character in CMake. You can use it if you double it though (\\).

Windows - MinGW

You must add MinGW's binary directory to your PATH environment variable. Doing this via Windows Settings can cause conflicts with other compiler toolchains, so we recommend adding it to build_overrides.cmake instead.

# build_overrides.cmake
set(ENV{QTDIR} "C:/Qt/6.2.4/mingw81_64") # or wherever Qt is located
set(ENV{PATH} "C:/Qt/Tools/mingw810_64/bin;$ENV{PATH}") # or wherever MinGW's binary directory is located

We use forward slashes (/) in the path because backward slash (\) is an escape character in CMake. You can use it if you double it though (\\).

Passing options to CMake

Any options passed to build.cmake on the command line will be forwarded to CMake during the configure step:

# Not recommended
cmake -P build.cmake -G Ninja  # build with Ninja 

But this still involves remembering options to pass them again next time. Instead, use build_overrides.cmake to store the options you require.

# build_overrides.cmake
list(APPEND CONFIGURE_ARGS -G Ninja) # build with Ninja

Now you don't need to specify options to build.cmake.

Tip: Advanced users can add conditional logic to build_overrides.cmake to set different CMake options depending on the value of an environment variable, or which version of Qt is being used. Study build.cmake to see how this kind of thing is done.

Running the compiled program

The compiled executable is located at:

• Linux: ${CMAKE_INSTALL_PREFIX}/bin/mscore
• macOS: ${CMAKE_INSTALL_PREFIX}/mscore.app/Contents/MacOS/mscore
• Windows: ${CMAKE_INSTALL_PREFIX}/bin/MuseScore4.exe

You can run it from that location, or if you compiled using the build.cmake script then you can run it with this command:

cmake -P build.cmake run

Also, on Unix-like systems:

./build.cmake run

You can specify additional arguments before or after run:

• Arguments before run are used internally by the build.cmake script.
  • These should match options used when you compiled (e.g. -G Ninja) in case they are needed to form the path to the installed binary.
• Arguments after run are passed to MuseScore on the command line.
  • E.g. -F to run with factory settings.

# Example workflow
cmake -P build.cmake -G Ninja         # configure, build and install with Ninja build system
cmake -P build.cmake -G Ninja run -F  # run the previously compiled program with factory settings

Running with factory settings

It is recommended that you always run development builds with the -F option to use factory settings. This applies to nightly builds as well as development builds compiled on your local machine or on GitHub Actions.

Running with -F prevents strange effects that can occur when default values for preferences are changed in the code by you or another developer. If you don't use -F and the strange effect occurs, there's a good chance that you will mistake it for an error in the code and then waste lots of time trying to fix it.

If you compiled using the build.cmake script, add the following line to build_overrides.cmake to always run with the -F option:

# build_overrides.cmake
list(APPEND RUN_ARGS -F) # run with factory settings

You can remove the line temporarily (or comment it out) when you need to check that the value for a particular preference does indeed persist between runs.

What to do if the build fails

At what stage does the build fail?

The configure step fails

If the build fails during the configure step (initial CMake run), it's probably because a dependency is missing or because you provided the wrong options to CMake. Follow the instructions in the error messages to fix the problem, then try running the build.cmake script again.

The build step fails

If it fails during the build step (compilation) it could be due to mistakes in the code (unlikely if you haven't changed anything) or because library header files were not found. If it fails at the very end of the build step (linking) then it's probably because a library object file was not found. Fix the code, or install the library, and try again.

The install step fails

If it fails during the install step then it could be because you don't have permission to install to the location in question. CMake installs files to a system-wide location by default, but our build.cmake script overrides this to install within the build directory, so permissions shouldn't be a problem.

MuseScore fails to run

If you managed to compile the program but it won't launch, or if it launches but strange things happen, try running with factory settings. If the error still occurs, make sure:

• All necessary shared libraries are installed and in the right location.
• Qt Plugins are installed and in the right location.

Failures in general

In general, if the build fails then you should find clues in the terminal output. Paste the error messages into a search engine to see if other people have had the same problem. If all else fails then you should create a post in the Technology Preview Forum to ask for help. Upload your build log as a .txt file attachment to the post. Paste a link to your post in the #development channel of MuseScore's Discord Server so we can find it quickly and provide help if we can.

Tip: Advanced users can also take a look at MuseScore's CI scripts and try to use the same process on their machine, but be careful! The CI scripts are intended to run inside a virtual machine that gets wiped after every build. Some of the steps may not be safe to try on a local machine.