1.0 Setting Up A Build System

I am assuming you are using MacOS 10.14.6 (Mojave) or later and Xcode 10.3; these instructions have not been tested on earlier versions.

Installing Xcode

Install Xcode if it is not already installed on your Mac. I will assume you are using Xcode version 10.3.

After installing Xcode, you may also want to install the command line tools. To do this, go to Xcode > Open Developer Tool > More Developer Tools…, login using your existing Apple ID, then choose the latest Command Line Tools download.

Creating a command line tool Xcode project

In the Welcome to Xcode window, click on Create a new Xcode project, or choose File > New > Project… from the Xcode main menu.

Under the MacOS tab, choose the Command Line Tool Application type and click the Next button.

Here’s how I filled out the next dialog box (but you should feel free to enter whatever you like here):

Next you will be asked to specify a directory in which to create the project. This location is entirely up to you. I chose /Users/plewis/Documents. For this choice of parent folder, Xcode created the following folder structure:

Users/
    plewis/
        Documents/
            strom/
                strom.xcodeproj
                strom/
                    main.cpp

Setting up Xcode to use the C++11 standard

We will use the C++11 standard for this tutorial. As of this writing, C++17 is the latest C++ dialect. You are welcome to use the C++17 dialect, but because this tutorial does not use any C++ features that are not in the C++11 standard, I will show how to set up Xcode and external libraries to use C++11 so that third-party libraries will link correctly to the tutorial. If you decide to go with C++17, be sure to use C++17 when compiling every library or you will have difficult-to-diagnose errors at the link step.

In the Xcode Project Navigator pane on the left, you should now see your strom project (beside a blue project icon ), and inside that you should see a strom folder (beside a yellow folder icon ), and inside that you should see a file named main.cpp. (If you do not see anything like this, it may be because your Project Navigator pane is not visible. You can always get it back using View > Navigators > Show Project Navigator from the main menu.)

Click once on the strom project (with the blue project icon ) in the Project Navigator, then select the strom TARGET within the project settings shown in the central pane. You should now see General, Resource Tags, Build Settings, Build Phases, and Build Rules across the top of the central pane.

Click on Build Settings, All (not Basic or Customized), Levels (not Combined), and then type “C++ Language Dialect” into the Search box to filter out all build settings except the one we are interested in at the moment.

In the “C++ Language Dialect” row, double-click on the column with the blue project icon (this is the column for the project settings, the other column labeled strom contains target-specific settings). This should allow you to choose C++11 [-std=c++11] as your C++ dialect.

Running the default “Hello, World!” version of the program

Press the run button () in the tool bar and your minimal “Hello, World!” program should compile and run successfully.

Setting up Xcode to save an optimized executable

Throughout most of this tutorial (and especially for this first Hello, World! program), you will not need to optimize your executable for speed to run the examples, but you will want to create an optimized release version of your executable to use for real data examples, where the speed is essential. To create an optimized version, you need to select Archive from the Product main menu in Xcode. The optimized version will be stored in an out-of-the-way part of your hard drive where Xcode keeps its archived products (you can find where this is by going to the Xcode Preferences… menu item and clicking on the Locations tab). Xcode also stores this location in an environmental variable $ARCHIVE_PRODUCTS_PATH. It is a pain to extract your executable from this obscure location each time you need it (even though Xcode gives you a button to save it somewhere else), so let’s set up a post-action script to automatically copy the release version to a directory that is on your executable path and thus can be run from anywhere.

Start by choosing the Xcode Product menu item while holding down the Option key, then selecting the Archive… menu item. (Note: if the menu item is Archive and not Archive…, then you failed to hold down the Option key while selecting the Product menu item). Another way to do this is to use the key combination Command-Option-r and then click on Archive in the left panel.

Expand the Archive action by clicking on the triangular disclosure button on the left. This allows you to add a post-action. Add a New Run Script Action by pressing the + button at the bottom left of the post-action panel and replace # Type a script or drag a script file from your workspace to insert its path. with the following small script:

exec > "/tmp/xcode_run_script.log" 2>&1
cp "$ARCHIVE_PRODUCTS_PATH/usr/local/bin/strom" /Users/plewis/bin

You will, of course, need to change some parts of this, because you are not me, but the script is pretty simple. The first line uses the exec command to save all output to a temporary file named /tmp/xcode_run_script.log. This allows you to see what went wrong if anything does go wrong in the copying process. The second line simply copies the executable (named strom) from the Xcode archive location ($ARCHIVE_PRODUCTS_PATH/usr/local/bin) to a directory of your choice. I have used the bin directory inside my home directory /Users/plewis, which is a directory I created for storing programs that I want to be able to run from anywhere. I made this happen by adding this directory to my PATH environmental variable in my $HOME/.bash_profile file:

export PATH="$HOME/bin:$PATH"

Be sure to specify /bin/bash as the Shell to use for interpreting your post-action script, then press the Archive button to create the release executable. From now on, whenever I ask you to create a release version of your program, you can simply choose Archive from the Product menu and your post-action script will automatically copy your program to the directory you specified!