Skip to content

Latest commit

 

History

History
165 lines (99 loc) · 6.86 KB

README.md

File metadata and controls

165 lines (99 loc) · 6.86 KB
Raw

heimdall-osx-arm64

Heimdall specifically built for ARM64 macOS.

I made this initially only as a reference for myself in the future because I couldn't find any prebuilt binary for ARM64 macOS, also I had a hard time building Heimdall on my M1 MacBook Pro.

Downloads

Download from Releases section.

Even if you download a prebuilt binary, you still have to install Homebrew and its dependencies. (except cmake which is only required for building). More details can be seen below. Homebrew isn't needed to run the app bundle. However, the CLI binary needs libusb that is also included in the app bundle. You can get it too from a package manager like Homebrew.

Installing

With the release of heimdall-osx-arm64 2.0.2, you don't have to deal with the complexity of the old steps. Simply unpack the app and you're ready to go! 🥳

macOS quarantine may stop you from running the app because the app isn't signed. Try right-clicking the app on Finder and click Open, or remove quarantine extended attributes with this command:

xattr -drs com.apple.quarantine /path/to/heimdall-frontend.app

If you're finding the heimdall executable, it's located in the same directory as heimdall-frontend:

/path/to/heimdall-frontend.app/Contents/MacOS

Building

Warning These instuctions are partly obsolete for now. Stay tuned for the new ones.

Make sure you already have Homebrew and Xcode Command-Line Tools installed to simplify the process of getting the dependencies and building.

To install Xcode Command-Line Tools, run this command:

xcode-select --install

Install CMake, libusb and Qt5 through Homebrew.

brew install cmake libusb qt@5

The original Heimdall hasn't been updated since 2017, and Samsung has updated Odin protocol on their latest devices, which broke the original Heimdall. Moreover, the original Heimdall can't be compiled with Apple Clang anymore. After lots of trials and errors in trying different versions and forks, I found Henrik Grimler fork works best. It's also still actively maintained.

Clone the repo to get the source code.

git clone https://git.sr.ht/~grimler/Heimdall

Change to the repo directory.

cd Heimdall

Switch to the latest stable version. At the time of writing, the latest stable version is v2.0.2. You can check by running git tag.

git checkout tags/v2.0.2

Run cmake to configure things.

cmake . \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=/usr/local \
    -DQt5Widgets_DIR=/opt/homebrew/opt/qt@5/lib/cmake/Qt5Widgets

Export LIBRARY_PATH environment variable pointing to Homebrew lib folder, to avoid linking issues.

export LIBRARY_PATH=/opt/homebrew/lib

Finally, run make to build and install.

make
sudo make install

You'll see that heimdall is now installed in /usr/local/bin and heimdall-frontend in /Applications.

To check that everything works, run heimdall.

heimdall info

It should output like this:

Heimdall v2.0.2

Copyright (c) 2010-2017 Benjamin Dobell, Glass Echidna
https://www.glassechidna.com.au/

This software is provided free of charge. Copying and redistribution is encouraged.

If you appreciate this software and you would like to support future development please consider donating:
https://www.glassechidna.com.au/donate/

Heimdall utilises libusb for all USB communication:
    https://www.libusb.info/

libusb is licensed under the LGPL-2.1:
    https://www.gnu.org/licenses/licenses.html#LGPL

In the other hand, heimdall-frontend should run, but it can't find heimdall binary. If you click Detect in Utilities tab, you will see this output.

FRONTEND ERROR: Failed to start Heimdall!

That's because it's located in /usr/local/bin which is not in user-scope PATH.

Run this command to add the directory to PATH.

sudo launchctl config user path "/usr/local/bin:$PATH"

Reboot your Mac. Now you should see the following output once you click Detect.

ERROR: Failed to detect compatible download-mode device.

Or this if you've connected your phone.

Device detected

Building without Frontend

If you don't want to use heimdall-frontend, or you want to use another frontend like JOdin3, you can just build the heimdall binary.

Do all steps in Building section, with some changes.

You don't need to install Qt5, as it's only needed by heimdall-frontend.

brew install cmake libusb

Remove Qt5Widgets_DIR and append DISABLE_FRONTEND option in cmake.

cmake . \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=/usr/local \
    -DDISABLE_FRONTEND=ON

Once you've done everything, you'll only get heimdall binary located in /usr/local/bin.

Notes

  • This binary does not have built-in libraries; instead it relies on libraries provided by Homebrew. Because of that, you must not uninstall Homebrew, libusb and Qt5. (if you use heimdall-frontend) Otherwise the binary would crash.

    I'm still thinking about building heimdall statically and bundling Qt5 to heimdall-frontend, but I haven't found a way to do it.

  • Although Heimdall repository provides a "driver" for macOS, I don't think you'll need it. I haven't got any problems so far, apart from some warnings which are fine for now. You can't even use the driver without disabling SIP or System Integrity Protection which will prevent you from running iOS apps until you enable it. The driver is codeless and signed so it should be able to be installed.

  • For those who don't know yet, you can only do one read-write operation on Heimdall at one session, unlike Odin. For example, if you've run heimdall flash --no-reboot or heimdall print-pit --no-reboot once, the second time would fail with errors like ERROR: Protocol initialisation failed!. See this issue.

    If you want to run another operation, reboot your phone to Download Mode again.

Many thanks to: