Compile instructions (Windows - MSVC with Qt Creator)

Updated 3 years ago

    This page is instructions for how to use the MSVC compiler inside the Qt Creator IDE. This is useful to take advantage of Qt-specific features, like visual editing of UI files in Qt Creator's Design mode.

    Getting the MSVC compiler

    With Visual Studio

    If you don't mind having multiple IDEs, the easiet way to get what you need to to follow the Prerequisites section of the guide for Visual Studio and then return here when done.

    Without Visual Studio

    Microsoft makes their build tools available separately to the Visual Studio IDE, so if you are using Qt Creator as your IDE then in theory it should be possible to compile MuseScore without also installing Visual Studio. Unfortunately this doesn't seem to be working at the moment, so the best thing to do is to follow the instructructions above to install with Visual Studio.

    If you really want to try without Visual Studio (e.g. if short on disk space) then you can try installing just the C++ build tools. This has worked in the past, but fails with linker errors when last tried (November 2020). It's possible this could be fixed by using the right combination of include statements in MuseScore's header files, or by choosing the right combination of options in Microsoft's build tools installation wizard.

    To install only the C++ build tools:

    1. Visit this page and scroll down to All Downloads.
    2. Expand the Tools for Visual Studio section.
    3. Download Build Tools for Visual Studio.

    Run the installer you downloaded, and when you get the the Workloads screen, ensure the C++ build tools option is checked. That's the only thing you need.

    You can optionally look under the Individual components tab, where you should see the following items checked:

    • Under Compilers, build tools and runtimes
      • C++ [year] Redistributable Update
      • C++ CMake Tools for Windows
      • MSVC v[version] - VS [year] - C++ x64/86 build tools (v[version])
    • Under Debugging and testing
      • Testing tools core features - Build Tools
    • Under Development activities
      • C++ Build Tools core features
    • Under SDKs, libraries and frameworks
      • Windows 10 SDK ([version])
      • Windows Universal C Runtime

    It's possible that you don't need all of those components, but installing them does no harm (assuming you have enough space on your drive).

    Getting the CDB debugger

    The Windows 10 SDK offered with the Build Tools installer does not include debugging tools by default. To get the CDB debugger for Windows, you need to modify the SDK installation to include it.

    1. In the Start menu, search for Add or remove programs and open it.
    2. Find Windows Software Development Kit in the list of installed programs.
    3. Click on it and select Modify. An installation dialog pop up.

    4. Select Change and click Next. You should see this screen:

      Windows_SDK.PNG

    Select the Debugging Tools for Windows option and click Change.

    Getting the Qt libraries and Qt Creator

    If you already have Qt installed then you can simply run the Maintenance Tool that came with it (the tool is in C:\Qt or wherever you installed Qt). If you don't have Qt already installed, you need to download the Qt Online Installer for Windows and run that instead.

    Ensure the following components are checked within the Maintenance Tool / Online Installer:

    • Under the latest Qt 5.12 (currently Qt 5.12.9), the master branch meanwhile ( 484f8dc, 09Oct2020) even requires Qt 5.15 (currently Qt 5.15.1) and a C++17 capable toolchain, which comes as part of MSVC 2017/2019 and the MinGW for Qt 5.12 and later anyway).
      • Select the prebuilt libraries for your MSVC compiler version (e.g. MSVC 2017 64-bit, MSVC 2019 64-bit for Qt 5.15)
        • The MSVC year does not have to match the version you installed earlier (though ideally it should)
        • The MSVC architecture must match the version you installed earlier
          • 32 bit Windows: you must install the 32 bit libraries
          • 64 bit Windows: you can choose either the 32 or 64 bit libraries, or both!
            • If in doubt, install only the 64 bit libraries. That is enough to compile MuseScore for your own machine. The 32 bit libraries are only useful if you want to compile for 32 bit computers.
      • Select Qt WebEngine

    If you want to be able to debug within Qt Creator (recommended), also check:

    • Under Developer and Designer Tools
      • Qt Creator (cannot be deselected)
      • Qt Creator CDB Debugger Support

    Click Next to install these components.

    Getting the other dependencies

    Download dependencies.7z and extract the contents into the base directory. (This will create a new dependencies folder in that base directory.)

    Also install Jack.

    Compiling on the command line

    It's a good idea to make sure you can compile from the command line before you try to set up an IDE.

    The following batch script has the commands need to set up the build environment and compile MuseScore. Modify the paths as neccesary for your machine, then save the file as msvc_build.bat inside your MuseScore code repostory.


    REM Add Qt to PATH
    SET "PATH=C:\Qt\5.12.9\msvc2017_64\bin;%PATH%"

    REM Set up build environment (next line optional, but uncomment it if compiler is not found)
    REM CALL "C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Auxiliary\Build\vcvars64.bat"

    REM Tell MSVC to use all processor cores
    SET "CFLAGS= /MP%NUMBER_OF_PROCESSORS%"
    SET "CXXFLAGS= /MP%NUMBER_OF_PROCESSORS%"

    REM Create build directory
    IF not exist "my_build_dir\" MKDIR "my_build_dir"
    CD my_build_dir

    REM Configure, build and install MuseScore
    cmake .. -DCMAKE_BUILD_TYPE=RELWITHDEBINFO -DCMAKE_INSTALL_PREFIX=my_install_dir
    cmake --build . -j %NUMBER_OF_PROCESSORS%
    cmake --build . --target install

    ECHO "Executable location: my_build_dir\my_install_dir\bin\MuseScore4.exe"

    Add the script's filename to .git/info/exclude to prevent it from being checked-in to the repository.

    To run the script:

    1. In the Start menu, search for CMD.
    2. Type cd (change directory) followed by a space and the path to your MuseScore code repository
      • e.g. cd C:\Users\[username]\MuseScore
      • Press Enter to run the cd command
    3. Type the name of the file msvc_build.bat and press Enter to run it.
    4. If you need to run it again, simply press the Up arrow key to get the previous command back and press Enter to run it again.

    The following shortcuts make command prompt much easier to use:

    • Up and Down arrow keys: cycle through commands previously typed in this session
    • Tab key: autocomplete a command, filename, or path (i.e. type a few characters then press Tab)
    • Ctrl+C: stop a command that is taking a long time to complete
    • Ctrl+Shift+C copy highlighted text (must be enabled in CMD Properties, see below)
    • Ctrl+Shift+V paste text (must be enabled in CMD Properties, see below)

    Clicking the CMD icon in the top left corner of the window brings up a menu with useful options, including Edit and Properties. You might want to go into Properties and enable "Use Ctrl+Shift+C/V as Copy/Paste". These are the standard copy and paste shortcuts available in most Command Prompt / Terminal applications on Windows and Linux.

    Note: there are two other primary build modes, debug and release. Debug is not currently supported for MSVC due to linking errors.

    Working in Qt Creator

    IDEs are convenient for experienced users, but they introduce another layer of complexity. If something goes wrong then you might not know whether the issue is with the IDE or the compiler.

    Editing files

    To retain control over the compile process, you could choose to ignore Qt Creator's IDE features and just use it as a text editor for MuseScore's .cpp, .h and .ui files. Simply keep your Command Prompt open in a separate window, and press Up and Enter every time you want to recompile.

    To set up a basic project where Qt Creator is only used as a text editor:

    1. Within Qt Creator, go to File → New File or Project
    2. Select "Import Project" and "Import Existing Project"
    3. Enter project details:
      • Name: "MuseScore" (or "MuseScore_Windows" if you share this folder with another OS)
      • Location: "~/src/MuseScore" (or wherever the Git repo is on your system)
    4. Choose the files to include in the project:
      1. Filter the list by filetype:
        • Add *.ui to the list of types shown
        • Add * to the list of types hidden (hides everything else)
        • Now apply the filter.
      2. Choose which files to include:
        • Uncheck all directories except libmscore, mscore and mtest
      • Click "Next".
    5. [Optional] Add the project to Git version control.
      • You may prefer to use Git from the command line (recommended) or an external GUI tool.
    6. Click "Finish".

    Debugging

    You can debug inside Qt Creator even if the program wasn't built in Qt Creator.

    To set this up within your Qt Creator project:

    1. Click Projects in the left panel
    2. Find your Build Kit (e.g. Desktop Qt 5.15.1 MSVC2019 64-bit) on the left (you may only have one).
    3. Click the Build project option.
    4. In the CMake section, change the CMAKE_INSTALL_PREFIX option to the directory where you would like your compiled binary to be installed. (eg, C:\mscore-win64install). Click Apply Configuration Changes to commit your change.
    5. Under the Build steps, expand the Details menu. Check lrelease and uncheck all.
    6. Under Build Steps click Add Build Step/CMake Build. Under the Targets, check install and uncheck all. (Sometimes the checkbox list will be blank initially. If you click on another project and then click back this will often refresh the list)
    7. Click on the Run project option. In the Run Settings window, under Run click Add... and then Custom Executable. You can now enter the custom path for your executable here. For example:
      • Executable: C:\mscore-win64install\bin\MuseScore4.exe
      • Arguments: -F (if you always want to debug in MuseScore's initial state)
      • Working directory: %{buildDir}

    Now when you want to debug, go to the Debug menu > Start debugging > Start debugging without deployment.

    If you try to debug and see the message "Unable to create a debugging engine", make sure that you installed the Debugging Tools inside the Windows SDK and installed CDB Debugger Support in Qt Creator as explained earlier. If it still doesn't work then go to the Projects tab in the left panel, click "Manage Kits" and make sure the correct debugger is selected for you chosen kit.

    Custom compilation

    To avoid having to open CMD, you can tell Qt Creator to run your mybuild.bat script for you every time you press a compile button with Qt Creator itself. This gives you the best of both worlds: you get the convenience of an IDE but still have the flexibility and reliability of a separate build script.

    To get Qt Creator to use your build script:

    1. Click Projects in the left panel
    2. Find your Build Kit (e.g. Desktop Qt 5.12.9 MSVC2017 64-bit) on the left (you may only have one).
    3. Click the Build button to edit the build configuration and do the following:
      1. Delete any existing Build Steps, then click Add Build Step > Custom Process Step
        • Command: mybuild.bat
        • Working directory: %{buildDir}
      2. Delete any existing Clean Steps, then click Add Clean Step > Custom Process Step
        • Command: msvc_build.bat
        • Arguments: clean
        • Working directory: %{buildDir}

    Now when you want to build, simply press the big green triangle with the bug in the bottom left of the screen. When you want to delete the build files and start again, go to the Build menu and choose "Clean Project".

    Full project set-up

    MuseScore uses the CMake build system. The "proper" way to set up a CMake project in Qt Creator is as follows:

    1. Go to File > Open File or Project
    2. Choose MuseScore's top-level CMakeLists.txt file

    Qt Creator will spend a few minutes "configuring" the project, but once that's done everything is set up all ready for you to click "build". There's no need to go messing around with build and debug configurations, as Qt Creator does this automatically. At least, that's the theory...

    In practice, the automatic method is vulnerable to changes in the CMake files, and it tends to break fairly often without reason. This forces you to run the configuration again, which takes a few minutes in Qt Creator (and other IDEs) but only takes a couple of seconds on the command line.

    Ultimately, the most reliable way to compile is to copy whatever is done inside the build scripts used for MuseScore's CI tests. Build scripts will always use a command line method rather than an IDE.