+++++++++++++++++++++++ MACOS BUILD WALKTHROUGH +++++++++++++++++++++++ Mark Liversedge Ale Martinez Mar 2025 Version 3.7 A walkthrough of building GoldenCheetah from scratch on Mac OSX. This was performed on macOS Sonoma (14.4) but the instructions are largely the same for all current versions of macOS. CONTENTS 1. BASIC INSTALLATION WITH MANDATORY DEPENDENCIES - Xcode - HomeBrew - Qt - GSL - Bison 2. ADDING OPTIONAL DEPENDENCIES - FTDI D2XX - SRMIO - libusb - libical 1. BASIC INSTALLATION WITH MANDATORY DEPENDENCIES ================================================= Depending upon the speed of your internet connection and availability of the required software the steps in section 1 will take approximately 1 hour. 1.1 Ensure macOS is up-to-date ------------------------------ Make sure you have applied all the latest updates to Mac OS X. This can be found from the system menu, apple, about this mac, software update. This walkthrough was performed on a MacBook Air running 15.4 (Sequoia) 1.2 Install XCode from App Store -------------------------------- To install Xcode on macOS you need to download it via the App Store. You can launch the App Store from launchpad, or it may be already in your dock. Under the search box type in Xcode and it will return a few options, generally Xcode is the first item and shows a blueprint with a hammer icon. Click on this to install it. It should be free. The usual app store process will apply as the application is downloaded and installed. The download is about 4GB so do bear this in mind if you have limits on your internet bandwidth or cap. 1.3 Run the Xcode installer --------------------------- The app store download will have added an Install Xcode icon in the launchpad. Go ahead and run it. Xcode includes all the development tools such as a compiler, debugger and SDKs. It also installs the 'git' tool for working with Git repositories. It will run through a wizard to install, just read and then accept the license agreement and let it get on with it. If you don't like the license then quit and use the developemnt or snapshot builds from https://www.goldencheetah.org 1.4 Get the source code ----------------------- We store all the Golden Cheetah source code on github.com, it is a great site holding repositories for many open source projects. First open up a terminal session, then; $ cd $ mkdir Projects $ cd Projects $ git clone https://github.com/GoldenCheetah/GoldenCheetah.git You will now have the GoldenCheetah sources downloaded into a 'GoldenCheetah' directory in your home directory, under another folder called 'Projects'. $ cd GoldenCheetah $ ls You should see a number of directories such as doc, qwt, src etc. If you are wanting to build a particular release you need to checkout the release. To build a release you need to checkout the code at the tag for the release. A list of releases can be found at: https://github.com/GoldenCheetah/GoldenCheetah/tags $ git checkout V3.7 $ ls The following walkthrough is based on latest master, if you want to build v3.7 please see the AppVeyor scripts in the repository. 1.5 Install HomeBrew -------------------- The easiest way to install GoldenCheetah dependencies on macOS is via HomeBrew package manager, if you don't have it installed yet, follow the instructions in their home page: https://brew.sh/ 1.6 Install Qt -------------- Latest stable release can be installed as: $ brew update $ brew install Qt6 Follow the instructions to add Qt to PATH and test using: $ qmake --version You can also install Qt5 this way currently, but if you want to install other specific Qt version you need to download and install the Qt SDK from http://qt-project.org/ You can use a browser to download and run the interactive installer and select a Qt version, including at least the following modules: - Desktop macOS - Additional Libraries - Qt WebEngine under Extensions Once this step is completed add the bin directory to PATH and test qmake is ok: $ qmake --version For v3.7 we are using both Qt 5.15.2 and Qt 6.8.3 LTS versions. 1.6 Install GSL and Bison ------------------------- GSL is a mandatory dependency from v3.7, you can install using HomeBrew: $ brew install gsl The Bison version included in Xcode is too old (2.3), you can install a newer version using HomeBrew: $ brew install bison adding it to PATH as indicated, check version using: $ bison --version 1.7 Configure and Build GoldenCheetah (with no optional dependencies) --------------------------------------------------------------------- First thing we need to do is set the build configuration, this means editing the private build profile settings. There is one for qwt (a charting library) and there is another for GoldenCheetah itself. $ cd ~/Projects/GoldenCheetah/qwt $ cp qwtconfig.pri.in qwtconfig.pri $ cd ../src $ cp gcconfig.pri.in gcconfig.pri $ vi gcconfig.pri In that last step you can use whatever editor you feel most comfortable with. we may need to additionally configure to use the local compression libraries (at least I did), by adding the following line: LIBS += -lz and GSL location: GSL_INCLUDES = /usr/include GSL_LIBS = -L/opt/homebrew/lib/ -lgsl -lgslcblas -lm Lastly, we can also uncomment and change the following line: QMAKE_MOVE = cp if Bison version is higher than 3.7 Once the changes have been made we are now ready to build for the first time. $ cd .. #this should put you in the top level dir containing this file $ qmake -recursive $ make When build first time you get number of error messages on .qm files missing: "RCC: Error in 'Resources/application.qrc': Cannot find file 'translations/gc_fr.qm'" You can ignore these messages for your build. The .qm files will be created during the build at a later point in time via the "lrelease" command you configured in gcconfig.pri) Once this completes you will have a GoldenCheetah.app in the src directory which can be launched: $ open src/GoldenCheetah.app And you're up and running. Now, if you would like to use XCode to debug the project, you can generate the necessary project file. $ qmake --recursive -spec macx-xcode This will create a project as: build.xcodeproj Please be sure to build via the standard method before checkin to prevent build errors. If the build fails to launch with "couldn't be opened because you don't have permission to view it" Then a work around would be to open the project and attach the debugger. $ open src/GoldenCheetah.app 2. ADDING OPTIONAL DEPENDENCIES =============================== - D2XX - SRMIO - libusb - libical - Python embedding - R embedding Since these optional dependencies are more complex and require more advanced technical skills we do not provide a walkthrough for building them all but instead provide the configure settings and any special considerations that should be taken into account. See src/gcconfig.pri.in for instructions and the AppVeyor CI scripts in the repository for examples about the changes you need to make: - appveyor/macos/install.sh - appveyor/macos/before_build.sh and then rebuild. If you plan to use Cloud Services, you need to obtain the proper API keys for the service, a detailed example can be found in GoldenCheetah Developers Guide https://github.com/GoldenCheetah/GoldenCheetah/wiki/Strava-configuration