Skip to content

Compiling on Macs with Apple Silicon

Jump to bottom Edit New page
Casper Jeukendrup edited this page Mar 7, 2024 · 24 revisions

Note: if you are not using a Mac with Apple Silicon, please ignore the contents of this page.

If you have a Mac with Apple Silicon, you have several options for compiling MuseScore. You can compile either in ARM64 mode ("native mode") or x86_64 mode ("Intel mode"; will use Rosetta 2 when running on Apple Silicon Mac). Soon, it will also be possible to create a Universal build, combining both architectures in one executable.

Update: Since we switched to Qt 6 for the master branch, compiling on ARM64 Macs just works, exactly the same as on Intel Macs. So you can basically ignore this page. We will still keep it though, in case anyone ever needs it.

If you already have Qt installed, you should choose the method that matches your Qt installation:

  • If you have installed Qt 6, you should compile in ARM64 mode.
  • If you have installed Qt 5.15.x via Homebrew (or otherwise have an ARM64 version of Qt), you should compile in ARM64 mode.
  • If you have installed Qt 5.15.x via the Qt Online Installer (or otherwise have an x86_64 version of Qt), you should compile in x86_64 mode.
  • If you have a Universal version of Qt 5.15.9 or higher, for example self-built, then you can create a Universal build of MuseScore.

If you have not yet installed Qt, we recommend building natively (ARM64 mode) as it is the simplest and easiest option.

Contents

Setup

  1. Install Homebrew:

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

    Follow the instructions that appear after running this command.

  2. Install CMake, Ninja and Git:

    brew install cmake ninja git

Compiling in ARM64 mode

Experimental support for arm64 mode has been added for Apple Silicon Macs.

  1. Install Qt:
  2. Install libsndfile: brew install libsndfile
  3. Install pkg-config: brew install pkg-config

You are ready to build! See Compiling from the Command Line.

Compiling in x86_64 mode

Install Qt via the Qt Online Installer as described here: Install Qt and Qt Creator.

Method 1: Using a Dual Homebrew Installation

Because you are building MuseScore in x86_64 mode, you must also install libsndfile in that mode. Otherwise, it will cause linker errors. Below are instructions for how to do this.

Generally, you can use arch -x86_64 command to run command in x86_64 mode. This should ask you to install Rosetta 2 if you haven't done that yet. We will use this to install Homebrew in x64_64 mode, which allows us to install libsndfile in x86_64 mode.

Homebrew behaves differently in x86_64 mode. In ARM64 mode, it puts its packages in /opt/homebrew/bin. In x86_64 mode, it puts packages in /usr/local/bin. If you installed Homebrew correctly, /opt/homebrew/bin should appear in the $PATH variable before /usr/local/bin. This means that your shell will first look in /opt/homebrew/bin when searching for the brew command or any packages installed so that the ARM version will be used by default. If you want to use the x86_64 version instead, you must prepend /usr/local/bin to the $PATH variable. You can do that by prepending PATH=/usr/local/bin:$PATH to a command (or by running export PATH=/usr/local/bin:$PATH, but that will affect all future commands in the current session). Note that we use colons here (:), not semicolons.

  1. Install HomeBrew in x86_64 mode: 
    arch -x86_64 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  2. Install pkg-config and libsndfile in x86_64 mode: 
    PATH=/usr/local/bin:$PATH arch -x86_64 brew install pkg-config libsndfile

You are ready to build! See Compiling from the Command Line.

Tip: You can set an alias for HomeBrew in x86_64 mode. For example, in your shell profile (~/.zprofile, ~/zshrc, or ~/.profile), you can add:

alias brew_intel="PATH=/usr/local/bin:\$PATH arch -x86_64 brew"

This allows you to use it like:

brew_intel install pkg-config libsndfile

Method 2: Creating a Dedicated Iterm2

If you use the Iterm2 terminal application, and you don't need to use Homebrew for anything else, you can alternatively use the following method.

The first thing you'll want to do is dump (you can use brew list to list all of the installed packages) and uninstall your ARM brew if you have it. Of course, you should ensure you aren't using any of these packages for another dev environment. If so, you may want to check out Method 1: Using a Dual Homebrew Installation.

Then, use these instructions for installing Iterm2:

  1. Download Iterm2 I386 shell (or any other supporting running in I386 arch mode)
  2. Unzip and move Iterm2 to your Applications folder
  3. Duplicate Iterm2, and name the duplicated item "Iterm2 Rosetta"
  4. Right-click on it, and choose "Get info"
  5. Inside the info panel, check "Open using Rosetta"

Now when you open this terminal and enter arch, it should display i386 (entering arch on your standard M1 terminal would show arm64).

This will provide a safe I386 sandbox on your M1 machine, which may also be used for other I386 projects.

All the following commands for this method will be entered in the Rosetta Iterm2 you created.

Installing Dependencies in I386 Brew Mode

  1. Install Homebrew in I386 mode in Rosetta Iterm2 (if you haven't already): 
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  2. Install required dependencies: 
    brew install cmake ninja git pkg-config libsndfile

This way, the linker will be happy having pkg-config and libsndfile in I386 mode, and having other brew commands running in I386 mode will not be a problem compared to the mess of managing multiple brew modes (you will only need ARM brew if you have other development libraries requesting link in ARM).

At this point, you may choose to install the packages you dumped from your ARM brew.

You are ready to build! See Compiling from the Command Line.

Compiling from the Command Line

Now that we have these things installed, we can start building MuseScore. Important: if using x86_64 Method 2, the following commands need to be run in the Rosetta Iterm2 as well.

Firstly, we need to find the path to Qt.

  • If you installed Qt 6.2.4 using the Qt Online Installer, it is usually found at ~/Qt/6.2.4/macos/bin.
  • If you installed Qt 6.2.4 using HomeBrew (ARM64), it is usually found at /opt/homebrew/Cellar/qt/6.2.4/bin.
  • If you installed Qt 5.15.x using the Qt Online Installer (x86_64), it is usually found at ~/Qt/5.15.x/clang_64/bin.
  • If you installed Qt 5.15.x using Homebrew (ARM64), it is usually found at /opt/homebrew/Cellar/qt@5/5.15.x/bin.
# In the root directory of the project, run:
PATH_TO_QT=~/Qt/6.2.4/macos/bin # Your Qt location (see above)

Compiling:

  • If you are compiling in ARM64 mode, run: 
    PATH=$PATH_TO_QT:$PATH ./build.cmake -DMUE_COMPILE_BUILD_MACOS_APPLE_SILICON=ON
    The last part of the command enables the flag for experimental Apple Silicon support.
  • If you are compiling in x86_64 mode, run: 
    PATH=$PATH_TO_QT:/usr/local/bin:$PATH ./build.cmake
    The reason to include /usr/local/bin at the start of $PATH is so that when CMake searches for pkg-config and libsndfile, it will find them in /usr/local/bin first, where they are installed from using x86_64 Homebrew.

Note that the body of the command is in both cases just ./build.cmake. See Compile on the command line for information about this script.

The PATH=… prefix of the command ensures that the $PATH variable is set correctly. When CMake searches for a package, it will look in the directories mentioned in $PATH one by one, starting by finding Qt.

You probably don't want to specify those PATHs every time you run the script. As described on the page about build.cmake, you can also specify these things in a build_overrides.cmake file:

set(ENV{QTDIR} "$ENV{HOME}/Qt/6.2.4/macos") # or wherever Qt is located; note that we are not adding "/bin" to the path
set(ENV{PATH} "/usr/local/bin:$ENV{PATH}") # only include this line if building for x86_64

If your build is failing, this is often due to corrupted configuration files from a previous failed build. Delete all directories inside builds, then start again, following the wiki closely.

Compiling with Qt Creator

After installing the required packages using one of the methods above, you should also be able to compile MuseScore in Qt Creator using these instructions: Compile in Qt Creator.

If you are compiling in x86_64 mode, you may need to set the value of CMAKE_PREFIX_PATH to /usr/local/bin;%{Qt:QT_INSTALL_PREFIX} (the default is %{Qt:QT_INSTALL_PREFIX}) in the CMake Options section. This is so that the x86_64 mode packages are found correctly.

Common issues

macOS asks "MuseScore would like to access files in your Desktop folder" too often

Every time that you have compiled MuseScore, macOS should ask this one time (one time per folder: Desktop, Documents, Downloads). But on Apple Silicon Macs, the security is a bit more strict; this causes macOS to ask permission again and again, for every single operation MuseScore does with the file system. So, also when loading the list of recent files, macOS will ask it for each recent file again. This is annoying and not workable. The solution is to codesign the compiled MuseScore app. That means running the following command:

codesign --force --deep --sign - /path/to/install/directory/mscore.app

where /path/to/install/directory is the path specified in CMAKE_INSTALL_PREFIX.

In Qt Creator, this can be done too:

  1. Go to Projects mode
  2. Go to "Run"
  3. Under Deployment, click "Add Deploy Step" and then "Custom Process Step"
  4. Enter the following information:
    • Command: codesign
    • Arguments: --force --deep --sign - /path/to/install/directory/mscore.app where /path/to/install/directory is the path specified in CMAKE_INSTALL_PREFIX.
    • (Working directory does not matter.)

If the install directory is /Users/casper/Desktop/MuseScore/MuseScore4_Qt6.install, then the result should look like this:

Setting up the codesign step in Qt Creator
Add a custom footer

Testing

Translation

Compilation

  1. Set up developer environment
  2. Install Qt and Qt Creator
  3. Get MuseScore's source code
  4. Install dependencies
  5. Compile on the command line
  6. Compile in Qt Creator

Beyond compiling

  1. Find your way around the code
  2. Submit a Pull Request
  3. Fix the CI checks

Misc. development

Architecture general

Audio

Engraving

Extensions

Google Summer of Code

References

Clone this wiki locally