VESC-BUILD-MACOS-UNIVERSAL.md

VESC macOS Universal Build

Some parts referenced from https://www.downtowndougbrown.com/2023/08/how-to-create-a-qt-5-arm-intel-universal-binary-for-mac/

I will be working on a Mac Studio M2 with macOS 14.5. But these instructions should work on any Mac with macOS 12.0 or later. I will also be downloading and building in $HOME/qt but feel free to change VESCBUILDBASE to another folder you with to use.

The resulting build will be in /opt/external/qt-5.15.14 so change the -prefix option if you wish to change that. Also feel free to change -j8 to a higher number if you have more cores available to speed up the build.

Open up Terminal and let's get started!

Qt and Xcode

• Create our /opt/external folder and give ourselves permission to write to it:
  • sudo mkdir -p /opt/external && sudo chown $USER /opt/external
• Create our build folder and export it as VESCBUILDBASE:
  • mkdir -p "$HOME/qt" && export VESCBUILDBASE="$HOME/qt" && cd $VESCBUILDBASE
• Download and extract Qt 5.15.9+ (5.15.14 used here):
  • wget qt-everywhere-opensource-src-5.15.14.tar.xz https://download.qt.io/official_releases/qt/5.15/5.15.14/single/qt-everywhere-opensource-src-5.15.14.tar.xz && tar -xf qt-everywhere-opensource-src-5.15.14.tar.xz
• Download and extract Xcode 14.0.1 (which is the last version supporting the macOS 12 SDK):
  • You need to login to the Apple Developer portal before you can navigate to https://download.developer.apple.com/Developer_Tools/Xcode_14.0.1/Xcode_14.0.1.xip. Once you login you can download the file manually to $VESCBUILDBASE.
  • Now extract with: xip -x Xcode_14.0.1.xip
• Create a qt-build folder outside of Qt sources for our build:
  • mkdir -p "$VESCBUILDBASE/qt-build" && cd "$VESCBUILDBASE/qt-build"
• Make sure we are using the downloaded Xcode by exporting the DEVELOPER_DIR:
  • export DEVELOPER_DIR="$VESCBUILDBASE/Xcode.app/Contents/Developer"
• Run ../qt-everywhere-src-5.15.14/configure QMAKE_APPLE_DEVICE_ARCHS="x86_64 arm64" -opensource -confirm-license -nomake examples -nomake tests -no-openssl -securetransport -prefix /opt/external/qt-5.15.14 in qt-build
• You can take a peek at the resulting .qmake.stash file to confirm that it is using our downloaded Xcode.app if you like.
• Run make -j8 in qt-build
• This took about 15 minutes on my Mac. Get coffee and wait for the build to finish.
• Run make -j8 install in qt-build
• Get more coffee and wait another couple minutes for the install to finish.

Congrats, you should now have a Universal Binary build of Qt at /opt/external/qt-5.15.14:

❯ ls -al /opt/external/qt-5.15.14
total 0
drwxr-xr-x   11 andy  admin    352 Jul 30 15:05 .
drwxr-xr-x    3 andy  admin     96 Jul 30 14:55 ..
drwxr-xr-x   56 andy  admin   1792 Jul 30 19:59 bin
drwxr-xr-x    4 andy  admin    128 Jul 30 14:55 doc
drwxr-xr-x   24 andy  admin    768 Jul 30 15:01 include
drwxr-xr-x  189 andy  admin   6048 Jul 30 19:59 lib
drwxr-xr-x   79 andy  admin   2528 Jul 30 19:58 mkspecs
drwxr-xr-x   15 andy  admin    480 Jul 30 19:59 phrasebooks
drwxr-xr-x   31 andy  admin    992 Jul 30 15:07 plugins
drwxr-xr-x   27 andy  admin    864 Jul 30 19:59 qml
drwxr-xr-x  347 andy  admin  11104 Jul 30 19:59 translations`

VESC Tool Modifications

We need a clone of the VESC Tool repository and some modifications to the build process to make it work with our new Qt build. Feel free to use a folder other than $VESCBUILDBASE if you wish. But these steps will clone into the same folder as the Qt build.

On my macOS ARM build it tries to write a file named QCodeEditor which conflicts with the folder name which is why we move it to src/include and include from there instead.

• Clone the VESC Tool repository:
  • cd $VESCBUILDBASE
  • git clone https://github.com/vedderb/vesc_tool.git
  • cd vesc_tool
• If you are wanting to build a specific version you'll need to checkout that versions branch:
  • git checkout release_6_02
• At this point if you have built firmware you can copy them to the res/firmwares folder. Otherwise you can skip this step. But you will need to add exclude_fw to the CONFIG variable when we build with `qmake later on.
• Edit the vesc_tool.pro file and and modify the following lines:
  • QMAKE_APPLE_DEVICE_ARCHS should be modified to be: QMAKE_APPLE_DEVICE_ARCHS = x86_64 arm64
  • include(QCodeEditor/qcodeeditor.pri) should be modified to be: include(src/include/QCodeEditor/qcodeeditor.pri)
• Edit the qmarkdowntextedit/markdownhighlighter.cpp file and modify the following line:
  • #include "QCodeEditor/include/internal/QSyntaxStyle.hpp" should be modified to be: #include "src/include/QCodeEditor/include/internal/QSyntaxStyle.hpp"
• Move the QCodeEditor folder to the src/include folder:
  • mkdir -p src/include
  • mv QCodeEditor src/include

Build VESC Tool

We can now configure and build the VESC Tool with our new Qt build. I am re-exporting variables we may have set earlier because I happen to be doing the VESC Tool build in another terminal window.

• Export some variables to make the build process easier:
  • export VESCBUILDBASE="$HOME/qt"
  • export DEVELOPER_DIR="$VESCBUILDBASE/Xcode.app/Contents/Developer"
  • export PATH="/opt/external/qt-5.15.14/bin:$PATH"
  • export LDFLAGS="-L/opt/external/qt-5.15.14/lib"
  • export CPPFLAGS="-I/opt/external/qt-5.15.14/include"
• Run qmake to configure the build:
  • If you don't have firmware available be sure to add exclude_fw like: qmake -config release "CONFIG += release_macos build_original exclude_fw"
  • Otherwise, you can run: qmake -config release "CONFIG += release_macos build_original"
• Time to build the VESC Tool:
  • make -j8
• Now bundle up the QML and framework:
  • macdeployqt "build/macos/VESC Tool.app" -qmldir="$PWD" -always-overwrite

You should now have a working VESC Tool Universal Binary build in build/macos/VESC Tool.app. Try running it on an Intel and ARM Mac to confirm it works on both architectures.