Compile instructions (Windows - Visual Studio)

Updated 4 days ago

Note: these instructions are for building using the Visual Studio IDE with the 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.

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

How to build MuseScore

  • Checkout MuseScore source code, see Suggested workflow. Make sure the path to the MuseScore sources is
    • not too long
    • doesn't contain spaces
    • doesn't contain any non-ASCII letters (like e.g. a cyrillic username)
  • (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.
  • Download Visual Studio Community, if you do not already have VS2017/19 installed.
  • Follow the instructions in the section below labeled Installing Visual Studio 2017/19, even if do you already have VS2017/19 installed. Those instructions contain all the VS2017/19 setup and configuration instructions and details for MuseScore. If you already have VS2017/19 installed, you will probably need some reconfiguration, and you might need to modify your VS2017/19 installation.
  • Install Qt Tools Extension in Visual Studio
  • Install Qt tools:
    • Download the Qt Online Installer for Windows
    • Go to the latest 5.12 version (5.12.5 for now), or 5.9 (5.9.8 for now), in the latter case adjust the following instructions accordingly.
    • Install "Qt WebEngine" component
    • Install "msvc2017 64-bit" component (msvc2017 32-bit possible too, msvc2015 64-bit too but not recommended)
  • Add C:\Qt\5.12.5\msvc2017_64\bin to your PATH variable (C:\Qt\5.12.5\msvc2017\bin for 32-bit)
    • CMake "can't find resource" failures are probably because the Qt path is not set properly in PATH.
    • Make sure you removed mingw's C:\Qt\5.*\mingw*\bin entrance from the PATH if any
  • Download dependencies.7z
    • Extract the contents into the base dir. (This will create a new dependencies folder in that base dir.)
  • For VS2019 only: Modify msvc_build.bat and CMakeSetting.json and replace "Visual Studio 15 2017" with "Visual Studio 16 2019". Don't commit these changes to any PR.
  • Open Visual Studio
  • Open MuseScore folder from there (File->Open Folder...)
  • CMake must run automatically without errors
    • It takes a while. You need to make sure the background tasks are complete before continuing
  • Open the msvc.build_x64 folder
    • (note: to see this folder in the project’s file tree, the option “Show All Files” must be selected, otherwise, this directory will be hidden).
    • If no mscore.sln file was created, try running the msvc_build.bat file using the argument "relwithdebinfo". The batch file is located in your MuseScore folder.
  • Open the newly created mscore.sln file
    • You can use "Open Solution" from within Visual Studio interface, instead
      VS2017/19 Explorer
  • Build mscore project (by right clicking 'mscore' in the Solution Explorer and pressing "Build")
  • Build INSTALL project similarly 1
  • Run MuseScore from the msvc.install_x64/bin folder

How to debug MuseScore

  • Go through all the steps from the above build instructions
  • Right-click 'mscore' in Solution Explorer and click "Set as StartUp Project"
  • Right-click 'mscore' in Solution Explorer and click "Properties"
  • Under "Configuration Properties" tab, highlight "Debugging"
  • Set "Configuration:" combo-box on top-left to "All Configurations"
  • Set "Command" to $(ProjectDir)..\..\msvc.install_x64\bin\MuseScore3.exe (use $(ProjectDir)..\..\msvc.install_x86\bin\MuseScore3.exe for 32-bit)
  • Follow the Compile Instructions below to build an executable (or note from ericfont: I just had to just build mscore and INSTALL again...so I don't think need to follow entire Compile Instructions again)
  • Press <F5> or use the Debug menu options to launch the debugger
  • Keep an eye out for a popup console window which outputs debug info.
    • (This window might be hidden behind MuseScore's & Visual Studio's main window, so you might have to "Alt-Tab" to find it.)
    • If the external debug console window does not appear, the debug output window is probably going to the debug output window which appears in VS itself.
    • to output qCDebug statements for a particular QLoggingCategory (such as undoRedo), right click mscore and in debugging section, (e.g. for undoRedo, set the environment to have QT_LOGGING_RULES="*.debug=true;*undoRedo=true;undoRedo=true"

Advanced

  • Default configuration of the project is RelWithDebInfo which gives good performance and ability to debug symbols from within the Visual Studio. By the way, this configuration gives less debugging opportunities than Debug configuration and worse performance than Release configuration
    • To build MuseScore with other configurations you need to use msvc_build.bat script.
      • Make sure cmake is in your PATH, usually it is in %ProgramFiles(x86)%\Cmake\bin
    • This script allows building MuseScore with all configurations including both 32-bit and 64-bit
    • See beginning of the content of the script to get how it works
    • Don't forget to change the path to the Qt libraries when switching from 64-bit to 32-bit and visa versa
    • Delete msvc.build_x64 and msvc.install_x64 directories before running the script

Installing Visual Studio 2017/19

These instructions are for compiling MuseScore under Visual Studio 2017/19. Note that Visual Studio 2015 will probably work too, at least temporarily, but it has not been tested and is not recommended. As different Visual Studio versions can be installed side-by-side, it is best to install VS2017/19 Community Edition (or any other edition, if available), and to use it to compile MuseScore.
These instructions apply from revision f66e18a onwards, committed 6th August 2018, and applies only to the development version of MuseScore (master).

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. Regardless, VS2015, VS2017 and VS2019 are binary- and library-compatible, and the Qt version for VS2015 can be used with VS2017/19. Still it is recommended to use the Qt version for VS2017.

Installing and setting up the toolchain

You will need Visual Studio 2017/19 (any edition will do; Community Edition is full featured and free for open-source projects). Whether you have already installed it or not, please read these instructions carefully, as some dependencies might not have been installed.

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” screen. Make sure the “Desktop development with C++” option is selected (and any others you would like to use, of course).

Visual Studio 2017/19 install, selection of C++ workload

Next, select the “Individual components” tab at the top, and make sure the following options are all selected:

Code Tools: “Git for Windows”, "GitHub Extension for Visual Studio", “Help Viewer”

Visual Studio 2017/19 install, Code Tools

Compilers, build tools, and runtimes: “Visual C++ tools for CMake”, and ensure the latest toolset is available,

Visual Studio 2017/19 install, additional components (toolchain, CMake)

Note for VS 2019: this two are now called "C++ CMake tools for Windows" and "MSVC v142 - VS 2019 C++ x64/x86 build tools (v14.21)"

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, link it with your Microsoft account (if you don’t have one, create it!). Then, select Tools -> Extensions and Updates. On the left of the screen, select the “Online” options, enter “qt” in the search box on the top right, and select and install “Qt Visual Studio Tools”. Although this is not strictly needed, it can be handy later.

Add Qt Visual Studio tools to VS 2017/19

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!)

Getting and preparing pre-requisites

You will need a couple of utilities, programs and libraries to be able to compile MuseScore with Visual Studio:

7-Zip utility

To be able to handle compressed files. 7-Zip is open source, free, and quite powerful, but there are alternatives that will work as well.

Qt libraries

You will need the Qt libraries, version 5.12.5, to be able to compile MuseScore. Go to Get Qt, select the Open Source option, and follow the steps to execute the online installer. When asked, install the Qt 5.12.5 libraries for MSVC2017 64-bit, and optionally MSVC2017 32-bit. Install QWebEngine library.

NB: If you don’t install in the default location, you will need to modify some settings later on!

JACK

Download the Windows Installer (64-bit) for JACK from JACK @ GitHub (later on, if a 32-bit version of MuseScore is created, the 32-bit installer might be needed).

Install in the default location.

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 64-bit Windows.

Additional Dependencies

There are several additional dependencies:

  • libVorbis, libVorbisFile, libOgg
  • Portaudio
  • Libsndfile
  • LAME
  • Zlib

All of these are open-source projects. Although it is possible to download them individually and compile them to create the required libraries, it is easier to use pre-created libraries and include files. The file dependencies.7z contains all the required dependencies, and is easier to use. Download, and extract the contents into the base dir. (This will create a new dependencies folder in that base dir.)

Compile the project

Well! At last the step we were all waiting for! If any of the pre-requisites was not installed in its default location, start by editing the CMakeSettings.json file, and changing all referenced directories to the correct ones for your system. If this file is changed, it should not be sent as a proposed change to the master project.

If everything worked as it should, Visual Studio will have processed the CMakeLists.txt file in the root directory of the project, and created the corresponding Visual Studio Solution in the build.debug folder within the project (to see this folder in the project’s file tree, the option “Show All Files” must be selected, otherwise, this directory will be hidden). Note a small red “Stop” sign besides the build.debug directory: this means it is being excluded from the Git repository. Any directories or files with this icon are excluded.

Select again the “Team Explorer” tab in the right-hand pane on Visual Studio. In the “Solutions” section, you will find several Visual Studio solutions displayed. Double click the one named “mscore.sln” in folder “build.debug”. This will change the Solution Explorer’s view to show the solution and projects created by CMake in the previous step.

Opening the CMake-generated mscore.sln solution in VS2017/19

Now, on the right-hand panel, “Solution Explorer” tab,

  1. Right-click on the “mscore” project and click on “Set as StartUp Project”. This will ensure that this is the project that gets executed when a debugging session is started.

    Set startup project for debugging sessions in VS2017/19

  2. Select the version to build on the main toolbar of Visual Studio. Start by building “RelWithDebInfo” “x64” version (which should be selected by default).

    Select build target

  3. Right-click on the “mscore” project again, and click on “Build”, or, alternatively, select the mscore project by left-clicking on it (it should be highlighted), and on Visual Studio’s main menu select “Build” -> “Build mscore”. This will build all the dependencies of MuseScore, MuseScore itself, link all together to generate the executable file, and copy the required libraries to the output directory.

  4. Build "INSTALL" project in a similar way, but there's no need to select "INSTALL" as the startup project.

  5. Execute (or at least, try to execute) MuseScore by clicking on “Local Windows Debugger” on the main toolbar of Visual Studio (or, alternatively, right-click on the mscore project, and select “Debug” -> “Start new instance”).

Note: About Visual Studio Solutions and Projects

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 (a library, an executable, and so on). 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 subdirectory included (or, more precisely, one project for each target created with add_executable(), add_library(), and so on).


  1. Note, the INSTALL step is run manually and is mandatory only once, so unless you change external resources e.g. templates, workspaces, soundfonts, translations or change build configuration, there is no need to run the INSTALL step each time. ↩︎