Compile instructions (Linux & BSD) - Git

Updated 3 years ago

This guide is for compiling MuseScore from the source code for testing and/or contributing purposes. If you just want to test (and not contribute code changes) then you may find using a pre-compiled Development Build easier than compiling.

You shouldn't use this method to install MuseScore for everyday score editing. Instead, get the latest official release from the Downloads page. (Of course, if there's no package for your distribution then you have no choice but to compile.)

Get the source code

MuseScore uses Git for version control. Use these commands to get MuseScore's source code for building and testing purposes. (If you want to make changes to the code then substitute the clone URL for the URL of your own fork of MuseScore on Github, and also read Git Workflow.)

To get the latest code:

git clone git://github.com/musescore/MuseScore.git
cd MuseScore

Note: the "git clone" command will put the code in a new folder called "MuseScore", so we use "cd" to enter the MuseScore directory. All subsequent commands in this guide should be run from the "MuseScore" directory.

To get a specific branch or tag:

# Fetch only the files required by (for example) the v2.0.2 tag:
# Note: Simply remove "--depth 1" if your git doesn't have that argument.
git clone --depth 1 git://github.com/musescore/MuseScore.git --branch v2.0.2
cd MuseScore

This is useful if you were forced to compile MuseScore because no package was available for your distribution, or if you are building a package. Tags are more stable than development branches so their use is recommended in this situation.

Beware, the rest of this page might be deprecated

Please refer to the README.md in the git repository to get relevant information!

Build an executable file

Firstly, you should update the revision number that will be displayed in MuseScore's Help → About dialog. This is useful for tracking issues so this step should be done by everyone, including package maintainers. Simply do:

make revision

If you don't already have a copy of MuseScore installed on your machine then you can compile the usual way:

# This causes conflicts if multiple versions are present and therefore is NOT RECOMMENDED
make
sudo make install

This creates an executable file /usr/local/bin/mscore which can be run by typing mscore in the terminal.

However, if you do have (or plan to have) another version of MuseScore installed (e.g. via your distribution's package manager) then you'll probably want to be able to distinguish between them, so do this instead:

# Use SUFFIX and LABEL if multiple versions are installed to distinguish between them
make SUFFIX="-self" LABEL="Self Build"
sudo make SUFFIX="-self" LABEL="Self Build" install

NOTE: make install is required, even for development. Because when runtime, built executable (CMAKE_BINARY_DIR/mscore/mscore) needs some installed files, for example, soundfonts, which is located at `/usr/local/share/mscore-VERSION/sound/`. Running the built executable without make install will cause crash.

This creates an executable file /usr/local/bin/mscore-self which can be run by typing mscore-self in the terminal. Alternatively, you can click on the relevant icon from your desktop launcher:

The label "Self Build" allows you to distinguish your compiled version from any other versions you might have installed (e.g. official releases or nightly builds). You can set SUFFIX and LABEL to anything you want (but no spaces in SUFFIX).

Additional information

You can stop reading here if you want. The following section is not required. However, it may give you some tips about custom installation or optional post-installation tasks.

Custom installation path

Note: it is no longer necessary to use PREFIX to avoid $PATH conflicts when installing multiple versions (you can use SUFFIX and LABEL instead). Of course, you might have other reasons for using PREFIX.

If you want to install MuseScore elsewhere (not in the default location /usr/local), you can specify the path as follows:

make revision
make PREFIX=$HOME/software
make PREFIX=$HOME/software install

In this example, a local installation (only for the current user; no root privileges needed) is done. The resulting executable file is bin/mscore, located in the folder specified during build. For the above example, this gives $HOME/software/bin/mscore.

Keeping the source code up-to-date

Note: for more info about the development process with git, see Git Workflow .

The source code previously downloaded with git can be updated locally. Only new commits will be retrieved:

cd MuseScore
git pull

Note about the first command: the folder MuseScore is the one created by git and where you performed the compilation.

After updating you will need to compile again using:

# Remember to change SUFFIX and LABEL here if you set them to something else previously
make revision
make SUFFIX="-self" LABEL="Self Build"
sudo make SUFFIX="-self" LABEL="Self Build" install

'make' is clever and it will only get the compiler to compile the new files; unchanged files and files where no dependency has changed will not be recompiled, so it should be much faster than the initial compile. However, sometimes errors occur during compilation and it will be necessary to start again from scratch. To do this you must delete all of the intermediate object files (of which there are many!) that are created in the source code folder during compilation. Fortunately, there is a simple command to do this for you:

make clean

The next time you try to compile the code, it will start anew.

Note: before using make clean you should read the notes for "Uninstalling MuseScore" (immediately below).

Uninstalling MuseScore

There is a Makefile target to uninstall, so removing MuseScore is effortless:

sudo make uninstall

Obviously you must run this from within the MuseScore source code folder (created by git) where you performed the compilation.

Note:

You should always run make uninstall before you run make clean because it is not possible to do so afterwards.
When running make uninstall or make clean it is not necessary to specify any variables (PREFIX, SUFFIX, etc.) even if you specified them during compilation.
In the past there have been occasions where make uninstall was unavailable or broken on the latest development branch. In such cases, your last resort is to use a more arbitrary and dirty way to uninstall:
xargs rm < install_manifest.txt

Tools for editing and debugging

MuseScore is a sophisticated program made up of millions of lines of code split among thousands of files. Although it is possible to edit the code in any text editor and build from the command line, there are specialised tools to make the challenge of coding and spotting errors in such a huge project much easier to manage:

Before Debugging

These are some of the problems that you may or may not face while completing the next section.

1. The compile time for debug build will vary from 10 minutes (8 core system) to 1 hour (single core) depending on the number of cores that your system has.

2. One should disable the ClangCodeModel in the top bar under Help > Plugins > C++ otherwise you may get many C++ errors/issues. These don't prevent a build but may result in missing important warnings and real errors.

Parallel Build

If you have a multi-core/threading processor, compilation can be sped up significantly by allow Qt Creator to launch multiple parallel build processes. To achieve this, you can set -j$(shell getconf _NPROCESSORS_ONLN 2>/dev/null || getconf NPROCESSORS_ONLN 2>/dev/null || echo 1) in the Tool arguments for both the Build Steps as the Deployment Steps. You can also manually set the number of threads, e.g. -j8.
On a quad-core hyperthreading processor you could go up to `-j8` to maximize the processor load. It might be wise to set the number to be one lower than your maximal number of processes, allowing you to perform another program while the build is running.

Qt Creator IDE - method 1

This is the normal way (but not necessarily the best way) to configure Qt Creator for a CMake project. The advantage of this method is that Qt Creator does most of the setup and configuration for you. The disadvantage is that the CMake configuration can break from time-to-time when MuseScore's CMakeLists.txt are changed. This method also makes it more difficult to compile MuseScore from the Terminal should you need to do so.

If you haven't already, checkout MuseScore's code using Git (see main compilation guide above).
Within Qt Creator, open ./CMakeLists.txt as your project file.
When QT Creator asks for command line options for cmake, use
-G"Unix Makefiles" -DCMAKE_BUILD_TYPE=DEBUG
When QT Creator asks to Choose CMake Executeable, it's probably located at
/usr/bin/cmake

To install MuseScore so all features will be available (e.g. SoundFonts and templates) do the following:
In "Build settings" set the Cmake setting CMAKE_INSTALL_PREFIX to install. Remember to click "Apply Configuration Changes".
In "Run settings" add a deploy step where target is install (cmake --build . --target install). Then add a "Custom Executable" run configuration with executable set to %{buildDir}/install/bin/mscore (if that does not work, try %{sourceDir}/install/bin/mscore).

Qt Creator IDE - method 2

This method bypasses Qt Creator's built-in handling of CMake and simply specifies some Terminal commands to build and run MuseScore. This makes it easier to build MuseScore outside of Qt Creator and ensures that you always use an up-to-date CMake configuration.

If you haven't already, checkout MuseScore's code using Git (see main compilation guide above).
Within Qt Creator, go to File → New File or Project
Select "Import Project" and "Import Existing Project". Click "Choose".
Name: "MuseScore_Linux", location: "~/src/MuseScore" (or wherever the Git repo is on your system). Click "Next".
Add *.ui to the list of file types to be shown, and * to the list of types to be hidden (hides everything else) and then apply the filter.
Uncheck all directories except libmscore, mscore and mtest and then click "Next".
[Optional] Add the project to Git version control and click "Finish". (I prefer to use Git from the command line.)
Now click the "Projects" button on the left side of the Qt Creator window and modify the build and run configurations as follows:

Build settings

Build directory:
    ~/src/MuseScore (or wherever the code is located)

Build steps:
    make revision
    make installdebug PREFIX=install SUFFIX=-qt LABEL="Qt Creator Build" UPDATE_CACHE=FALSE

Clean steps:
    make uninstalldebug
    make clean

Build environment:
    Use System Environment

Run settings

Executable: build.debug/install/bin/mscore-qt  (this file won't exist until you run the build for the first time)
Working directory: %{buildDir}

Using the Makefile means that you always use the same build configuration as Travis. If the CMake options are changed by a PR then your configuration is updated automatically when you fetch and merge the changes from upstream.

Eclipse CDT

Download Eclipse CDT bundle or install the CDT on a previous eclipse install.
Edit ./CMakeLists.txt and change Project name to something different than "mscore" (if not, Eclipse will not find the mscore binary to run)
Create a musescore_build directory in the workspace and run Cmake to generate Eclipse project
mkdir musescore_build cd musescore_build cmake -G"Eclipse CDT4 - Unix Makefiles" -D CMAKE_BUILD_TYPE=Debug ../MuseScore
Open Eclipse.
- Import project using Menu File → Import
- Select General → Existing projects into workspace
- Browse where your build tree is and select the root build tree directory. Keep "Copy projects into workspace" unchecked.
- You get a fully functional eclipse project. Be patient, Eclipse will index all cpp files and build the project.
To debug, right click on the project and choose Debug as → Local C/C++ Application
Go to debugger tab, share libraries tab and uncheck Load shared library symbols automatically and Stop on shared library events
You should be able to debug.
If you lack sound, in Preferences → I/O, you can try to check PortAudio, APi: Alsa, Device: Pulse

More information: http://www.cmake.org/Wiki/Eclipse_CDT4_Generator