Compile instructions (Windows - Visual Studio)

Updated 1 year ago

Note: These instructions are for building MuseScore using the Microsoft Visual Studio 2019 (VS) integrated development environment with the Microsoft Visual C++ (MSVC) compiler. If you are familiar with the QtCreator IDE or want a better experience editing .ui files, see the instructions for Qt Creator and MSVC instead.

Maintainers: This guide is currently valid for Visual Studio 2019. Please update it for future VS versions rather than creating a new one.

1. Prerequisites

You will need the MuseScore source code, as well as several programs and libraries, to be able to build MuseScore with Visual Studio.

1.1 MuseScore source code

Check out the MuseScore source code (see the suggested workflow).
Make sure that the path to your MuseScore checkout folder:
- isn't too long;
  - Long paths can cause build errors. The longest path in the source tree is ~235 characters (may be different at time of reading). Windows MAX_PATH is 260, but could be shorter in certain instances.
- doesn't contain any spaces; and
- doesn't contain any non-ASCII letters (e.g., a Cyrillic username).
If you're using VS2017: Not recommended. Modify CMakeSettings.json and replace all occurrences of Visual Studio 16 2019 with Visual Studio 15 2017. Make sure not to commit these changes to any pull requests.

1.2 Visual Studio

These instructions are for building MuseScore with VS2019. Any edition of this version of Visual Studio should work, including the Community edition, which is full-featured and free to use for open-source projects.

Whether or not you already have Visual Studio installed, please read these instructions carefully, as you might need to install some additional components.

If you do not already have VS2019 installed, download Visual Studio Community.
When you run the Visual Studio installer (either for the first time, or after installing, to change options), you will get eventually to the Workloads tab. Make sure the Desktop development with C++ option is selected.
Switch to the Individual components tab and make sure the following options are all selected:
- VS2019:
  - Code tools:
    - Git for Windows
    - Help Viewer
  - Compilers, build tools, and runtimes:
    - C++ CMake tools for Windows
    - MSVC v142 - VS 2019 C++ x64/x86 build tools (v14.25) (or the latest version available)
    - Windows SDK, depending on your OS:
      - Windows 10 SDK (10.0.20348.0 or later)
        
        This version contains necessary WinRT libs
        
        If the above SDK does not show up in the VS Installer, you can find the appropriate SDK at the Microsoft SDK Archive.
      - Windows 11 SDK (latest)
    - Uncategorized:
    - GitHub Extension for Visual Studio
  - Note that as of 484f8dc, 09Oct2020, Qt 5.15 (and a C++17 capable toolchain, which with MSVC 2019 is a given) is required for the master branch.
Now, let it install (or update), grab a coffee (or a tea, a soda, a beer… whatever you prefer), and be patient.
Once Visual Studio has been installed, start it and link it with your Microsoft account. (If you don't have one, create one).
Go to Extensions > Manage Extensions (Tools > Extensions > Manage Extensions in older VS versions). On the left side of the dialog, select Online, then enter “qt” in the search box at the top right, and select and install Qt Visual Studio Tools. Although this is not strictly needed, it can be handy later.
While you are here, you can go to Tools > Options… and review and edit the editor options to your liking. (This can be done per-language, and there are tons of settings!)

1.3 CMake

CMake is used for generating the Visual Studio solution and project files needed for building MuseScore.

If you're building a standard build, Visual Studio will automatically use its own internal copy of CMake, so you don't need to download it separately.

If you're building an advanced build, you will need to download and install CMake.

(For information on the difference between standard and advanced builds, see building.)

Download and install CMake.
Add the CMake bin subfolder to the Path environment variable; typically, this will be %ProgramFiles%\CMake\bin.

1.4 Qt

You will need the Qt libraries, minimum version 5.15.2, to be able to build MuseScore. For the 3.x branch Qt 5.9 is sufficient (but the others work too, but as of 583c71c, 01Dec2020, the builds don't run when build with Qt 5.15, they crash on start or when opening a pre-3.6 score... no longer the case fortunately since at least 3.6RC), for the master branch as of 484f8dc (09Oct2020) you'd need 5.15. Go for 5.15.2, the latest and last publicly available Qt 5 release (MuseScore isn't yet ready for Qt 6, or the other way round).

Go to Download Qt: Get Qt Online Installer and follow the steps to download and launch the online installer.
If you're not in the US or Europe, you'll probably want to launch the installer with a specific mirror, as per https://wiki.qt.io/Online_Installer_4.x#Selecting_a_mirror_for_opensour…
Install Qt in the default location.
Ensure you select custom install
Choose a Qt version (5.15.2, but see above) and install the following components for that version:
- MSVC 2019 64-bit (Qt 5.15)
- Qt WebEngine (not needed anymore for the master branch)
- Qt Network Authorization
- Optional, for 32-bit builds of MuseScore: MSVC 2017 32-bit (not available for Qt 5.9.9; instead, install MSVC 2015 32-bit, which will also work for VS2017 and VS2019, or MSVC 2015 32-bit for Qt 5.15)
- Optional, to make debugging easier: Qt Debug Information Files (not available for Qt 5.9.9)
Add the path of the Qt bin subfolder (e.g., C:\Qt\5.12.9\msvc2019_64\bin) to the PATH environment variable.
Tip: If you get CMake “can't find resource” failures later on, it's probably because the path of the Qt bin subfolder has not been correctly added to the PATH environment variable.
Remove the MinGW C:\Qt\5.*\mingw*\bin folder from the PATH environment variable, if present.

1.5 JACK

NOTE: as of 1220175, 04Dec2020, JACK is no longer needed nor supported in the master branch, however it is needed if you wish to build 3.6.2 or earlier.

Download the 64-bit Windows installer for the latest version of JACK.
Install JACK in the default location.

1.6 7-Zip

You will need a utility that handles .7z compressed files. 7-Zip is open-source, free, and quite powerful, but there are alternatives that will work as well.

1.7 Additional dependencies

There are several additional dependencies:

LAME
libogg
libsndfile
libvorbis
libvorbisfile
Portaudio
WinSparkle
zlib

All of these are open-source projects. Although it is possible to download them individually and build them yourself to create the required libraries, it is much easier to use prebuilt libraries and include files.

Download dependencies.7z.
Extract the contents of dependencies.7z into the MuseScore checkout folder. (This will create a new dependencies subfolder within.)

NOTE: as of 1220175, 04Dec2020, LAME and PortAudio are no longer needed nor supported in the master (4.0) branch. They are still needed if you wish to build 3.6.2 or earlier versions.

2. Building

Before you can build MuseScore, you need to download and install all of the prerequisites.

MuseScore can be built in three different configurations:

Release: Runs fast with all performance optimizations enabled, but very difficult to debug.
Debug: Very easy to debug, but runs very slow because all performance optimizations have been disabled.
RelWithDebInfo: A compromise between Release and Debug. Runs faster than Debug but is more difficult to debug; conversely, easier to debug than Release but runs somewhat slower.

For each of these three configurations, MuseScore can be built for either 32-bit or 64-bit Windows.

A standard build of MuseScore uses the RelWithDebInfo configuration for 64-bit Windows. To build this, follow the procedure for a standard build.

To build MuseScore in other configurations, or for 32-bit Windows, follow the instructions for advanced builds.

2.1 Standard build

Open Visual Studio.
Go to File > Open > Folder… and open the MuseScore checkout folder.

Visual Studio will automatically begin to generate a CMake cache, which will include the Visual Studio solution and project files.

In Visual Studio, a solution is a collection of projects, grouped together, and sharing some basic characteristics. A project corresponds to a specific output being generated (such as an executable or a library). A project can exist by itself or within a solution, and a solution can contain one or more projects. CMake creates a single solution, with a different project for each logical component of MuseScore. The MuseScore solution contains over two dozen projects.

CMake cache generation will take a while. Watch the Output window and wait for the completion message to appear: CMake generation finished.

If everything has worked as it should, Visual Studio will have created a Visual Studio solution file called mscore.sln inside the msvc.build_x64 subfolder of the MuseScore checkout folder, along with a collection of Visual Studio project files (*.vcxproj).
The recommended process for running/building is:
- Go to File > Close Folder to close the MuseScore checkout folder.
- Go to File > Open > Project/Solution…, then navigate to the msvc.build_x64 folder and open the mscore.sln Visual Studio solution file.
The Solution Explorer window should look like this:

Note the small red “minus sign” icons to the left of each project. Those icons mean that the project files are being excluded from the Git repository. Any directories or files with this icon are excluded and will not be included in any commits that you make.
In the Solution Explorer window, select the mscore project, then go to Build > Build mscore. (Alternatively, right-click the mscore project and choose Build from the popup menu.)

Building will take a while. Visual Studio will automatically build all of the other projects that mscore depends on. Watch the Output window and wait for the completion message to appear:
========== Build: 25 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========
In the Solution Explorer window, select the INSTALL project, then go to Build > Build INSTALL. (Alternatively, right-click the INSTALL project and choose Build from the popup menu.)

Watch the Output window and wait for the completion message to appear:
========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========

Note: Make sure MuseScore4.exe is not running when building INSTALL.

2.2 Advanced builds

To generate an advanced build, use the msvc_build.bat batch file at a Command Prompt instead of building from within Visual Studio.

Exit Visual Studio if it's running.
Delete the msvc.build_x64 or msvc.build_x86 and msvc.install_x64 or msvc.install_x86 subfolders of the MuseScore checkout folder or run msvc_build.bat clean
Make sure that CMake is installed and that its bin subfolder has been added to the PATH environment variable.
Make sure that the bin subfolder of an appropriate build of Qt (e.g., 32-bit for a 32-bit build) is the one that has been added to the Path environment variable.
Open the msvc_build.bat batch file in a text editor (such as Notepad) to read the instructions in the comments at the beginning of the file.
Run the msvc_build.bat batch with the options you thing to need, e.g. msvc_build.bat RelWithDebInfo 32.

3. Running

Before you can run MuseScore, you must build it.

Run MuseScore4.exe from inside the msvc.install_x64\bin or msvc.install_x86\bin subfolder of the MuseScore checkout folder. (Do not run the copy of MuseScore4.exe inside the msvc.build_x64\main\RelWithDebInfo or msvc.build_x86\main\RelWithDebInfosubfolder of the MuseScore checkout folder.)

4. Debugging

Before you can debug MuseScore, you must build it.

Start Visual Studio and open the mscore.sln solution file.
Click the ▶ Local Windows Debugger button on the main toolbar, or go to Debug > Start Debugging, or press F5.
Watch the Output window for debug messages.