Compile instructions (macOS 10.10+) - Git (markdown WIP)

Use these instructions to compile MuseScore master branch on macOS 10.10+ (see http://doc.qt.io/qt-5/supported-platforms.html).

From revision 5b7c72a onwards, committed 9 March 2017, the development version of MuseScore (master) requires Qt 5.9 or newer and a C++11 capable toolchain.
The 2.x branches require Qt 5.4 however.

Although MuseScore 3.x can be built with Qt 5.12, it is currently (November 2019) a business requirement that it supports macOS 10.10 and 10.11. Qt 5.12 does not support these earlier releases, and, thus, MuseScore 3.x for macOS is released with Qt 5.9; therefore, you should build and test with that Qt release as long as this business requirement persists. Code intentionally or unintentionally depending on Qt features and even fixes since 5.9 will not work in the release.

Setting the build and development environment

1. Install the latest version of Xcode from the Mac App Store.
   • To see what the latest version of Xcode that is supported by a specific macOS version, see the Wikipedia Xcode#Version_comparison_table.
   • E.g. Xcode 8.2.1 is the latest version of Xcode supported on macOS 10.11.5 (column "min macOS to run")
   • For older versions of macOS that do not support the latest version of Xcode, download an older version. To download older versions of Xcode, https://developer.apple.com/download/more/ (tip: Click on Description twice to sort by reverse order, which will display all Xcode versions to the top)
2. Launch Xcode and accept the licence
3. In Xcode, go to Preferences -> Download and install the Command line Tools. With Xcode 5-8, you might need to run xcode-select --install instead.
   • In Xcode8, select the Command Line Tools version via Preferences -> Locations -> Command Line Tools (pick "Xcode 8.2.1 ..." from the drop-down)
4. a) Install the dependencies. If you are new to macOS development or do not have a preference, we suggest Homebrew
   ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
brew install libogg libsndfile libvorbis pkg-config portaudio jack lame cmake git
   b) If you prefer MacPorts, choose the DMG of your OS and install MacPorts Open a terminal and enter the following (in your home):
   sudo port install git libsndfile pkgconfig lame portaudio jack cmake
5. Qt is normally shipped via an online installer, which you should use if you are running the current version of macOS.
   • Download the open source version of Qt (not the commercial version), open the DMG and run the online installer. It will offer Qt 5.12. To get Qt 5.9, uncheck Latest releases, check LTS and press Refresh.
   • By default it will install Qt in your home directory. If you want to build a 2.x version of MuseScore, you also need to make sure to check Qt 5.4.2 for installation. To build MuseScore 2.x on older macOS versions, you should also install Qt 5.4.2 directly via the same online installer..
   • You only need to install the macOS and QT WebEngine components.
6. Append the following line to ~/.profile (or alternatively ~/.bash_profile if you already have it)
   export PATH=$PATH:~/Qt/5.9.9/clang_64/bin
   and run
   source ~/.profile
   or
   source ~/.bash_profile
7. Clone the repository from GitHub:
   git clone git://github.com/musescore/MuseScore.git

Xcode 8 specific notes

• Trying to compile MuseScore 3.x with Xcode 8 will fail with issue #298668: MuseScore compile issue on macOS 10.11.6 / Xcode 8.2.1 / Qt 5.9.8. This documents the workaround
• (You need to be in the MuseScore source directory). Configure the repository with the patch:
  git remote add mattmcclinch https://github.com/mattmcclinch/MuseScore.git
• fetch the 'xcode8' branch from its repository:
  git fetch mattmcclinch xcode8
• apply the patch
  git cherry-pick mattmcclinch/xcode8

If you plan to contribute to MuseScore, you can setup your own fork on GitHub and clone it instead. See the Git Workflow page.

Building MuseScore

1. In a terminal, enter:
   cd MuseScore
2. Set the revision SHA1 for this build
   make -f Makefile.osx revision
3. Start the actual compilation. It takes more than one hour on a MacBook 2 GHz but it's pretty fast on a MacBook Pro Core i7 (4 to 5 minutes max).
   make -f Makefile.osx release
4. Call the install target. The bundle is copied from the Release directory into the applebuild directory. All resources (such as help and templates) are added to it
   make -f Makefile.osx install
5. The package step. This target calls a script derived from this one. It creates a self-contained bundle, thanks to macdeployqt, by adding and stripping the Qt libraries into the MuseScore bundle. It also adds Qt plugins, PortAudio and libsndfile. A DMG file is the result
   make -f Makefile.osx package

Debugging and developing MuseScore

If you are a developer, look at the xcode target in the makefile. It generates a xcodeproj file. You can open this xcodeproj file and use the Apple IDE for tasks such as modifying, debugging and compiling MuseScore code. Run

make -f Makefile.osx xcode

Then open the xcodeproj bundle in Xcode

open build.xcode/mscore.xcodeproj

In Xcode, run the ALL_BUILD scheme. It will compile all the files. Then run the install scheme. It will install the required files (fonts, images etc...) for runtime. Debug by running the mscore scheme.

If MuseScore won't start

You may get this error message on the Xcode Console when you try to run the mscore scheme:

This application failed to start because it could not find or load the Qt platform plugin "cocoa".

This mean MuseScore can't find the Qt plugins. You need to edit the mscore scheme to set the environment variable QT_PLUGIN_PATH to point to your Qt plugins directory. The default value for Qt 5.9 is:

QT_PLUGIN_PATH=~/Qt/5.9.9/clang_64/plugins

The actual value you need to set depends on your Qt version and where you installed it earlier on. You may also need to expand the tilde (~) to it's full value /Users/ to point to your home directory. If MuseScore doesn't start for any other reason then try reverting to factory settings, but make sure you revert the compiled mscore debug build rather than the official version if you have it installed.

Debugging in Xcode 5+

In Xcode 5+, you might need to uncheck “Allow debugging when using document Versions Browser” in Product→Edit Scheme...→Run mscore.app. Otherwise --NSDocumentRevisionsDebugMode YES gets passed to MuseScore, and it doesn't know how to handle it. In Xcode > 5, you'll find the menu item elsewhere. Product→Scheme→Edit Scheme... Select Run (on the left hand side), and select Options along the top of the form. Then you'll find "Allow debugging when using document Versions Browser" in the form. Uncheck the checkbox.

Contributing

The preferred way to contribute is via a Pull Request on GitHub. Patches are also welcome on on the Issue Tracker.

Building a release for distribution

Dependencies built with Homebrew will not run on older versions of macOS. Here is a zip file with the dependencies as "bottles" built on Mac OS X 10.7. They can be installed with brew install {file}.tar.gz