Compile instructions (Windows - Visual Studio)
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).
- isn't too long;
- If you're using VS2017: Not recommended. Modify
CMakeSettings.json
and replace all occurrences ofVisual Studio 16 2019
withVisual 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)
- Windows 10 SDK (10.0.20348.0 or later)
- 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.
- Code tools:
- VS2019:
- 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 thePath
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 thePATH
environment variable.
Tip: If you get CMake “can't find resource” failures later on, it's probably because the path of the Qtbin
subfolder has not been correctly added to thePATH
environment variable. - Remove the MinGW
C:\Qt\5.*\mingw*\bin
folder from thePATH
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 newdependencies
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 betweenRelease
andDebug
. Runs faster thanDebug
but is more difficult to debug; conversely, easier to debug thanRelease
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 themsvc.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 themscore.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
ormsvc.build_x86
andmsvc.install_x64
ormsvc.install_x86
subfolders of the MuseScore checkout folder or runmsvc_build.bat clean
- Make sure that CMake is installed and that its
bin
subfolder has been added to thePATH
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 thePath
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\RelWithDebInfo
subfolder 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.