How to Compile Aseprite on Mac OSX 14.3.1
Essential Guide for Compiling Aseprite on Mac OSX 14.3.1
Keeping it Simple
I'm going to try to keep this as beginner-friendly as possible, but the following guide assumes that you have some basic knowledge of how to use the terminal and how to install software on Mac OSX. As such, it probably goes without saying - but - if you've already installed a specific dependency skip ahead to the next step.
- Xcode
- Homebrew
- Python
- Git
- Skia
- Aseprite Source Code
Xcode
To install Xcode, open the App Store and search for Xcode & install it. Once this is done, ensure that the MacOSX SDK is installed. You can check this by running the following command in the terminal:
xcrun --show-sdk-version
Which should show you something like this:
14.2
You can also check the location of the SDK by running the following command:
xcrun --show-sdk-path
Which should show you the full path to the SDK which won't be entirely useful yet, but it's good to verify that it's installed.
/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk
Once this is done, ensure that all the necessary command line tools are installed by running the following command:
xcode-select --install
This should automatically install a lot of the necessary dependencies we will need for compiling Skia & Aseprite.
Homebrew
The next step is to install Homebrew if you haven't already. You can do this by running the following command in the terminal:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Once done, you can verify that Homebrew is installed by running the following command:
brew --version
Which should show you the version of Homebrew that you have installed.
Brew Dependencies
The next step is to install the rest of the brew dependencies. This will include CMake & lua.
brew install cmake && cmake --version
brew install lua && lua -v
Python
If you don't have Python installed, you need to do that now. There are a couple ways you can do this on Mac OSX. You can either install it from the official website or you can install it using Homebrew. If you're installing it from the official website, download the .dmg file and verify the checksum as follows:
md5 /Users/username/Downloads/Python-3.9.7-*.dmg
You should see it line up with the checksum on the official website, e.g.,
0903e86fd2c61ef761c94cb226e9e72e
Once you've done this, run through the GUI installer and verify that Python is installed by running the following command which should show you the version of Python that you have installed.
python3 --version
Now, open the finder and navigate to the Applications folder. Open the Python 3.9 folder and double-click on the "Install Certificates.command" file. This will install the necessary certificates for Python to work properly. If you don't do this, you will almost definitely run into issues when trying to compile Skia.
Git
If you don't have Git installed, you need to do that now. You can do this by running the following command in the terminal:
brew install git && git --version
Skia
The next step is to create a working directory in your home directory & to clone depot_tools which will be used to build Skia.
mkdir $HOME/deps && cd $HOME/deps
git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git
Export the depot_tools directory to your PATH by running the following command which will allow you to use the depot_tools commands from anywhere in the terminal.
export PATH="$PATH:$HOME/deps/depot_tools"
Now we want to clone the latest compatible fork of Skia for Aseprite. You can usually find the correct version published in the Aseprite INSTALL.md. It'll usually look something like aesprite-x** where *** is the version number.
git clone -b aseprite-m102 https://github.com/aseprite/skia.git
Navigate to the Skia directory and build the dependencies by running the following script.
cd skia && python3 tools/git-sync-deps
If everything went well you should see a message like this:
Setting the following tools as active:
node-14.18.2-64bit
python-3.9.2-64bit
releases-upstream-2ddc66235392b37e5b33477fd86cbe01a14b8aa2-64bit
Next steps:
- To conveniently access emsdk tools from the command line,
consider adding the following directories to your PATH:
/Users/admin/deps/skia/third_party/externals/emsdk
/Users/admin/deps/skia/third_party/externals/emsdk/node/14.18.2_64bit/bin
/Users/admin/deps/skia/third_party/externals/emsdk/upstream/emscripten
- This can be done for the current shell by running:
source "/Users/admin/deps/skia/third_party/externals/emsdk/emsdk_env.sh"
- Configure emsdk in your shell startup scripts by running:
echo 'source "/Users/admin/deps/skia/third_party/externals/emsdk/emsdk_env.sh"' >> $HOME/.zprofile
So do as the message insists and run one of the commands to add the emsdk to your PATH. I used the following, but it really doesn't matter so long as it's available to the shell in which Aseprite is built.
echo 'source "/Users/admin/deps/skia/third_party/externals/emsdk/emsdk_env.sh"' >> $HOME/.zprofile
Now we want to use gn, which is a tool from Google that will be used to generate build files for Ninja which is a build system similar to Make, and will be used to pull our Skia modules together.
gn gen out/Release-x64 --args="is_debug=false is_official_build=true skia_use_system_expat=false skia_use_system_icu=false skia_use_system_libjpeg_turbo=false skia_use_system_libpng=false skia_use_system_libwebp=false skia_use_system_zlib=false skia_use_sfntly=false skia_use_freetype=true skia_use_harfbuzz=true skia_pdf_subset_harfbuzz=true skia_use_system_freetype2=false skia_use_system_harfbuzz=false target_cpu=\"x64\" extra_cflags=[\"-stdlib=libc++\", \"-mmacosx-version-min=10.9\"] extra_cflags_cc=[\"-frtti\"]"
To build Skia, we run the following. Depending on your system, this could take a while, or might not.
ninja -C out/Release-x64 skia modules
Aseprite Source Code
We're almost there.
The next step is to recursively clone the Aseprite source code from the official repository.
git clone --recursive https://github.com/aseprite/aseprite.git
Navigate to the Aseprite directory and create a build directory.
mkdir build && cd build
Before we run the final build step it's important to modify the following command block to your specific system. Verify the location of the MacOSX SDK defined by the DCMAKE_OSX_SYSROOT flag. The directory it points to should actually exist at be numbered, e.g., 14.2 or 14.3 or whatever version you have installed. If it doesn't, you need to change it to the correct version. It's also important to verify the location of DSKIA_DIR, DSKIA_LIBRARY_DIR, and DSKIA_LIBRARY. These should all point to the correct locations of the Skia source code and the built Skia library.
cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo \
-DCMAKE_OSX_SYSROOT=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX14.2.sdk/ \
-DLAF_BACKEND=skia \
-DSKIA_DIR=$HOME/deps/skia \
-DSKIA_LIBRARY_DIR=$HOME/deps/skia/out/Release-x64 \
-DSKIA_LIBRARY=$HOME/deps/skia/out/Release-x64/libskia.a \
-G Ninja ..
Once you've done this, you can run the final build step.
ninja aseprite
If everything went well, the build should compile and you should see a message like this:
[1544/1544] Linking CXX executable bin/aseprite
And that's it! You should now have a compiled version of Aseprite in the aseprite/build/bin directory. Launch it and verify that it works.
References & Materials
https://github.com/aseprite/aseprite/blob/main/INSTALL.md https://github.com/BabyGeek/aseprite-compile-mac-os-x
Notes
If SDKROOT throws an error, you can set it manually by running the following.
export SDKROOT=$(xcrun --sdk macosx --show-sdk-path)