Working with external libraries in C++ is extremely simple: all you have to do is declare a path to the resource you want to include or import a system library already defined in your project.
In iOS we can ignore most of the small steps we need to make manually to import libraries and SDKs thanks to Xcode’s amazing build settings tools. When working with libraries you’ll want to use some sort of versioned, dependency management tool, but how do you get started without getting stuck inside the internals of CMake in C++ projects?
A simple solution is to literally clone a repository and drag it into your project. This can then statically link your dependencies and they will always be there included in your shipped project. This doesn’t scale very well though when you are using a really common library across multiple projects.
MacOS has a great tool you can use called HomeBrew that lets you install a version of a library into your default HomeBrew library location and you can just
#include it into your project! Turns out doing things this way is super-convenient, but it gave me a bit of a headache coming at it from an Xcode point-of-view so I have made this tutorial to help you if you wanted to do things this way.
In this tutorial we’re going to install and include GLFW – a commonly used open-source OpenGL library.
Install the Library
Open up the terminal and ensure you have HomeBrew installed:
brew install glfw3
Simple as that! It will be installed by default to this path (which you can change):
You get to this visually by opening Finder,
cmd + shift + h and locating the
Importing a HomeBrew Library in your C++ Project
Now that you have your library its time to import it using CMake. Before you start to weep as I did, CMake is actually as simple or as complex as you want it to be but it is an incredible tool for essentially solving the same problems Xcode’s Build Settings and Target / Schemes features solve. What we want is to write this at the top of our file including the
main function (the entry point at where our program will run):
We always import the header file as this exposes the public parts of the library and that is all we need.
Head to your CMakeLists.txt file and lets add a sub directory to look in within our project that contains our HomeBrew libraries:
# add extra include directories include_directories(/usr/local/include)
It’s important to note that library header files are often stored in a separate
include folder like this one and the actual source inside a library folder.
Next let’s link (enable the compiler to go fetch the actual code which will run when the header files request to run methods or access functionality) our project with the library path itself:
# add extra lib directories from the library folder link_directories(/usr/local/lib)
You could be super-specific here but I’m going to leave it as the library path so it can find any other dependencies you want to include from the HomeBrew install location.
One you’ve added the add executable statement simply link the library with the project:
add_executable(your_app_name main.cpp) #find_package(glfw3 3.3 REQUIRED) target_link_libraries(your_app_name glfw)
This will now go and find the package, ensure it exists at version 3.3 and link it with our executable
The one gotcha is that GLFW requires OpenGL so we also need to do the same for that library which ships with MacOS itself.
find_package(OpenGL REQUIRED) target_link_libraries(untitled3 OpenGL::GL)
Using the Library
That’s it, you’re now good to go with GLFW in your project. Since you linked libraries in this way you access the library using angle brackets as mentioned above, but you could have simply provided a path to the source itself, but the linking would still have to have been done in the CMakeLists.txt file.