Compile instructions (Windows - MinGW) - Git

Introduction

From revision 5b7c72a onwards, committed 5th January 2018, the development version of MuseScore (master) on Windows requires Qt 5.9 or newer and a C++11 capable toolchain.

From revision 0128daf onwards, committed 1st November 2018, the development version of MuseScore (master) on Windows also builds with Qt 5.12 (and therefor in 64bit mode, since Qt 5.12.2 32bit is also possible). To build with Qt 5.9 or anything prior to Qt 5.12 (and therefore in 32bit mode only), or using MinGW 32-bit inQt 5.12.2 and later, the BUILD_64 setting needs to get switched off manually, this doesn't get detected automatically
As of 484f8dc, 09Oct2020, Qt 5.15 (and a C++17 capable toolchain) is required for the master branch. The 3.x builds don't run when build with Qt 5.15, as of 583c71c, 01Dec2020, it crashes on start or when opening a pre-3.6 score... Apparently and fortunately this seems to no longer happen, since at least 3.6RC, so it is again possible to build 3.x with Qt 5.15(.2).
The 2.x branches require Qt 5.4 however, as QtWebKit is needed, and that had been removed in post 5.4 versions of Qt for Windows.

To prevent any compatibility issues, it is essential to compile MuseScore with the same type and version of compiler as was used to build Qt.

N.B. The instructions on this page are only applicable to MuseScore from the above revision onwards. If you are compiling MuseScore 1.3, or an older revision of the git repo, you need to follow the older version of these instructions, as it may require different versions of Qt and GCC.

What you need

Tools

The following tools need to get installed on your computer.

7-Zip utility

Some of the files to be downloaded are compressed using 7-Zip compression. If necessary, download and install 7-Zip.

MinGW 5.3.0 and Qt 5.9 (or MinGW 7.3.0 and Qt 5.12 or MinGW 8.1.0 and Qt 5.15)

Fresh install:
Download the Qt Online Installer for Windows.

NB There are a number of Windows installers on this page - make sure it is the Online Installer you are downloading.

Run the installer and install Qt in C:\Qt. You just need the Qt libraries for MinGW 5.3.0 and the MinGW 5.3.0 toolchain (or those for MinGW 7.3.0 resp. MinGW 8.1.0)

(optional) Add the following directories to your %PATH%

C:\Qt\Tools\mingw530_32\bin
C:\Qt\Tools\mingw530_32\lib
C:\Qt\5.9.9\mingw53_32\bin
C:\Qt\Tools\QtCreator\bin

Update to Qt 5.9.9
Launch the Qt Maintenance Tool (C:\Qt\MaintenanceTool.exe).
First this tool will need to update itself, so select the Update components option. Once you've gone through all the steps, press the Restart button.

For this 2nd pass, select the Add or remove components option. In the select components screen, your currently installed components are preselected. Make sure to add ticks for the Qt libraries for MinGW 5.3.0 and that toolchain (see image from fresh install above).

CMake

Download the latest version of windows binaries for CMake. Choose the Windows (Win32 Installer) version. You need at least version 3.0. Versions up to 3.11.3 are known to work too (3.11 may emit some warnings reg. decrecated policies though). 3.5.1 is known to cause issues if not last in PATH.
As of 29. October 2020 the master branch requires Cmake 3.4 or later, but see below and use the one the Qt Installer provides, which is quite a lot newer.

Install in the default location (probably C:\Program Files\CMake or C:\Program Files (x86)\CMake) and optionally put the bin subdirectory into your PATH.
For 3.5 and later make sure it is in PATH after the 3 Qt mingw directories (see above).

The Qt Installer (see above) meanwhile does offer CMake too, and also auto-updates it at times, so might be the better choice.

Source Code

Get the source code from GitHub. If you need a Git client, you can try Git for Windows or the GitHub windows client.
git clone git://github.com/musescore/MuseScore.git

If you plan to contribute to MuseScore, you can setup your own fork on GitHub and clone it instead. See the Git workflow page.

Note: Directory names with spaces in them cause the build to fail; so avoid spaces in the name of your clone directory.

(optional but recommended) In your clone directory, copy the file build/git/hooks/post-checkout to the directory .git/hooks in order for mscore/revision.h to be maintained automatically by git. See build/git/hooks/README for details. Note that the .git directory is hidden.

%PATH% summary

You must have the following in your %PATH%:

• C:\Qt\Tools\mingw530_32\bin (or wherever MinGW is installed for you)
• C:\Qt\Tools\mingw530_32\lib (or wherever MinGW is installed for you)
• C:\Qt\5.9.9\mingw53_32\bin (or wherever Qt is installed for you)
• C:\Program Files\CMake\bin (or wherever you installed CMake)
• C:\Qt\Tools\QtCreator\bin If you want to launch QtCreator from the command line

NOTE: You can add path elements to cmd shells via Computer / System Properties / Advanced System Settings / Environment Variables. However, the make process can be sensitive to the rest of the contents of your %PATH% as well. If you encounter issues like mingw32-make immediately terminating with error code 0xc00000fd, then try stripping your path down to only the above elements, plus perhaps C:\Windows and C:\Windows\System32. You might consider running the build from a batch file that temporarily sets your %PATH% to just the required elements.

A good approach to doing so is to create the following batch file in the "C:\Qt" folder:

C:\Qt\qt.bat

@echo off
echo Setting up a MinGW/Qt only environment...
echo -- Set QTDIR to C:\Qt\5.9.9\mingw53_32
set QTDIR=C:\Qt\5.9.9\mingw53_32
echo -- Set PATH to %QTDIR%\bin
set PATH=%QTDIR%\bin
echo -- Adding C:\Qt\Tools\mingw530_32\bin;C:\Qt\Tools\mingw530_32\lib to PATH
set PATH=%PATH%;C:\Qt\Tools\mingw530_32\bin;C:\Qt\Tools\mingw530_32\lib
echo -- Adding %ProgramFiles%\CMake\bin
set PATH=%PATH%;%ProgramFiles%\CMake\bin
echo -- Adding to C:\Qt\Tools\QtCreator\bin
set PATH=%PATH%;C:\Qt\Tools\QtCreator\bin
echo -- Adding %SystemRoot%\System32 to PATH
set PATH=%PATH%;%SystemRoot%\System32
echo -- QMAKESPEC set to win32-g++
set QMAKESPEC=win32-g++
cd %USERPROFILE%
echo -- Set MAKEFLAGS to -j %NUMBER_OF_PRCESSORS%
set MAKEFLAGS=-j %NUMBER_OF_PROCESSORS%
rem un-rem the last line to start Qt Creator immediately
rem using /low makes sure you can still work with the PC
rem -lastsession gets you back where you left
rem start "" /low qtcreator -lastsession

Then create a shortcut to this batch file somewhere in the Programs menu. If starting QtCreator immediately, the shortcut can be set to "Start minimized".

(Note: if you don't want to launch qtcreator from a bat file, you can still set MAKEFLAGS to a hardcoded value directly inside of qtcreator by going to Projects->Build->"Build Environment" and adding a variable MAKEFLAGS with value "-j 4" for 4 or any number of compile threads.)

Dependencies

In addition to Qt, MuseScore depends on:

• portaudio to access Windows audio
• JACK to connect to JACK Server for MIDI and audio
• libsndfile for wav/ogg/flac output
• Ogg and Vorbis for support of ogg soundfonts
• LAME for support for MP3 (only the header files, lame_enc.dll is optional in master as of f99613f, but mandatory in 2.2 as of 2b8c11d, 27/28 Feb 2018)

NOTE: as of 1220175, 04Dec2020, PortAudio and LAME are no longer needed nor supported in the master branch.

One way is to put most of these dependencies directly in the MinGW include path. This may be ugly, but is pretty convenient. Either follow the below instructions or take this archive, unpack lib and i686-w64-mingw32 to C:\Qt\Tools\mingw730_32\ resp.C:\Qt\Tools\mingw530_32\ (C:\Qt\Tools\mingw491_32\ for 2.x branches) and Jack to C:\Program Files (x86)\ (these files are used for the development builds) or install just Jack and for the rest take Qt-additions.zip and unpack it into C:\.
As of 5d889d7 (27Apr2019) there is another and cleaner way (and one that also works for 64bit builds): use the same method as for the MSVS/VC builds, see https://musescore.org/en/handbook/developers-handbook/compilation/compi…, i.e. grab this dependencies.7z and extract the contents into the base dir. (This will create a new dependencies folder in that base dir.)

libVorbis, libVorbisFile, libOgg

The latest source also requires libraries for Vorbis and Ogg.
1. Get the library files for libVorbis and libOgg from: http://www.xiph.org/downloads
2. Copy the directories: include\vorbis and include\ogg into C:\Qt\Tools\mingw530_32\i686-w64-mingw32\include (Copy the entire directory so that you end up with C:\Qt\Tools\mingw530_32\i686-w64-mingw32\include\vorbis and C:\Qt\Tools\mingw530_32\i686-w64-mingw32\include\ogg)
3. Get the Vorbis Tools and copy libogg.dll, libvorbis.dll and libvorbisfile.dll into C:\Qt\Tools\mingw530_32\lib (You need to decompress the .7z file using 7 Zip)

Portaudio

1. Get portaudio.dll from a previous MuseScore install (bin directory) and copy to C:\Qt\Tools\mingw530_32\lib
2. Get portaudio.h from the current version at http://www.portaudio.com/download.html and copy to C:\Qt\Tools\mingw530_32\i686-w64-mingw32\include. You need to decompress the .tar.gz file using 7 Zip, as before.

NOTE: as of 1220175, 04Dec2020, PortAudio is no longer needed nor supported in the master branch.

JACK

1. Download the Windows installer (32-bit) for JACK from https://github.com/jackaudio/jackaudio.github.com/releases
2. Install
3. The build process assumes you installed in a directory Jack in your program files directory. The name of the program files directory can vary depending on the version and language of Windows. The environment variable %ProgramFiles% or %ProgramFiles(x86)% is used to find the directory. On an English version of Windows this will result in looking in C:\Program Files\Jack or in C:\Program Files (x86)\Jack on a Windows 64-bit

libsndfile

1. Windows binary available, choose Win32 http://www.mega-nerd.com/libsndfile
2. Install and go to the installation directory. The installation process is required to be run in administration mode.
3. Copy include\sndfile.h into C:\Qt\Tools\mingw530_32\i686-w64-mingw32\include
4. Copy bin/libsndfile-1.dll into C:\Qt\Tools\mingw530_32\lib

LAME

1. Download the current source files for LAME: http://lame.sourceforge.net/download.php
2. You need to decompress the .tar.gz file using 7 Zip, as before
3. Create a new folder in the C:\Qt\Tools\mingw530_32\i686-w64-mingw32\include directory called lame
4. Copy include\lame.h into C:\Qt\Tools\mingw530_32\i686-w64-mingw32\include\lame
5. (optional for master branch as of f99613f, but mandatory in 2.2 as of 2b8c11d, 27/28 Feb 2018, not needed nor used before that) Get lame_enc.dll (e.g. from the Qt-additions.zip below) and copy to C:\Qt\Tools\mingw530_32\lib

NOTE: as of 1220175, 04Dec2020, LAME is no longer needed nor supported in the master branch.

Compilation

If you wish to use the QtCreator IDE, follow the instructions in section "Qt Creator IDE", below.

Open a command line, possibly using a batch file such as qt.bat given above.
Browse to the directory where you checked out musescore
Enter
mingw32-make -f Makefile.mingw release
or
mingw32-make -f Makefile.mingw debug
Note that the two options internally set different flags for the compiler. In debug mode the QT_DEBUG flag is used, so conditional code controlled by #ifdef QT_DEBUG is compiled. In release mode NDEBUG is set. Unless you are building a release, it is suggested that you use the "debug" option, like in the section on the Qt Creator IDE (below).

Be patient ... On my Vista laptop (Intel T7550) it takes more than one hour to build. Build times on Windows can be more than twice as long as build times on Ubuntu (using the same computer). Once the compilation finishes, the MuseScore executable can be found in build.release/mscore/MuseScore.exe or build.debug/mscore/MuseScore.exe. So long as C:\Qt\Tools\mingw48_32\lib is in the PATH, it should not be necessary to copy any DLLs. However, it has been found necessary to copy the complete directories iconengines and imageformats from %QTDIR%\plugins to the build.release/mscore or build.debug/mscore directory (resulting in, for example, build.debug/mscore/iconengines. This should be sufficient for most development work.

Note: You may need to go into the preferences, and fix the paths to have Windows-style slash characters (backslash), or you may see error messages about not being able to open files. [Is this a bug?]

If you need the language files, instrument list, templates, and the normal directory structure of a installed version of MuseScore then type:
mingw32-make -f Makefile.mingw install

or, for a debug build:
mingw32-make -f Makefile.mingw installdebug

Once install has finished look in the current directory for win32install/bin/MuseScore.exe. In this case there is no need to copy DLLs or the plugins directories, as they are already copied during the make process.

Qt Creator IDE

Note: These instruction are know to work up to QtCreator 3.6.1. For instructions for QtCreator 4.x see Qt Creator 4.x compile instructions instead.

Once you setup everything above, you can open Qt Creator, either by typing start qtcreator from within a command prompt started as above, or by creating a separate batch file with start qtcreator as the last command.

Go to File ⇒ Open File or Project....

Choose CmakeLists.txt file type and open the file CmakeLists.txt from your source directory.

Now it will take you through a pathwizard:

1. Build Location:
   For the first Cmake run, it will offer a build directory such as MuseScore-build, if MuseScore is your checkout directory. Change this to choose a build directory of MuseScore/build.qtc instead.
   Please make sure the name of your build directory does not contain spaces.
2. Choose CMake Executable:
   Browse to where you installed CMake (i.e. C:\Program Files (x86)\CMake\bin)
3. Run CMake:
   Then input the following arguments for CMake:
   -DCMAKE_BUILD_TYPE=DEBUG -DCMAKE_TOOLCHAIN_FILE=build/mingw32.mingw.cmake -DCMAKE_INSTALL_PREFIX=../win32install

Note: the -DCMAKE_TOOLCHAIN_FILE=build/mingw32.mingw.cmake is needed the first time, but leads to a warning about being unused on subsequent times...
Note: as of 9caf157 (for the master branch) this file build/mingw32.mingw.cmake no longer exists and so the -DCMAKE_TOOLCHAIN_FILE=build/mingw32.mingw.cmake needs to get removed from the config.

As for the manual build, the supplementary DLLs should be found via C:\Qt\Tools\mingw530_32\lib in the PATH, so no further setting of environment variables should be required.

Before your first build or debug session, you will need to configure the Build, Deploy, and Run steps. Click Projects at left, then Build toward the top of the screen. Under Build Steps, expand the Details button and add a checkmark next to the lrelease target.
Then go back to the top of the screen and click Run. On this screen, you will first need to click Add Deploy Step. Select Make, then select install under Targets. Finally, you will need to click the Add button under Run Configuration to add a custom executable, and set it to %{sourceDir}\win32install\bin\MuseScore.exe.

To compile the debug build and start debugging go to Debug ⇒ Start debugging ⇒ Start debugging or simply click the debug icon. You have access to Qt help, completion, and debugging features!

Known problems

Note that there is a bug in the Qt Creator debugger. In some cases it will crash when a QPrinter object is instantiated (http://bugreports.qt-project.org/browse/QTBUG-14048). This happens when you print (of course!).