                                 +++++++++++++++++++++++
                                 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 travis 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
