Compile instructions (Windows - Visual Studio 2017)

Last updated 2018-12-07

How to build MuseScore

  • Checkout MuseScore source code, see Suggested workflow
  • Download Visual Studio Community, if you do not already have VS2017 installed.
  • Follow the instructions in the section below labeled Installing Visual Studio 2017, even if do you already have VS2017 installed. Those instructions contain all the VS2017 setup and configuration instructions and details for MuseScore. If you already have VS2017 installed, you will probably need some reconfiguration, and you might need to modify your VS2017 installation.
  • Install Qt Tools Extension in Visual Studio
  • Install Qt tools:
    • Download the Qt Online Installer for Windows
    • Go to the latest 5.9 version (5.9.7 for now)
    • Install "Qt WebEngine" component
    • Install "msvc2017 64-bit" component
  • Add C:\Qt\5.9.7\msvc2017_64\bin to your PATH variable
    • 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.9.7\mingw53_32\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.)
  • 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
      VS2017Explorer.png
  • 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 current configuration to RelWithDebInfo or Debug (if not already set).
  • Set "Command" to $(ProjectDir)..\..\msvc.install_x64\bin\MuseScore3.exe
  • 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.)

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

Installing Visual Studio 2017

These instructions are for compiling MuseScore under Visual Studio 2017. 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 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 and VS2017 are binary- and library-compatible, and the Qt version for VS2015 can be used with VS2017.

Installing and setting up the toolchain

You will need Visual Studio 2017 (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 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 install, Code Tools

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

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

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

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.9.7, 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.9.7 libraries for MSVC2017 64-bit, and optionally MSVC2015 32-bit (right now, Musescore compiles as a 64-bit app, the 32-bit libraries will be useful if the compile is changed to 32-bit). Install QWebEngine library (which needs MSVC2017 64-bit).

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

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 keep in hand, as it will be needed in a later step.

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

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

  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. 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 or translation, there is no need to run the INSTALL step each time. ↩︎