Adding External Libraries and Frameworks

Adding External Libraries and Frameworks

Pre-built libraries

To link a library to your Axmol application, then simply add this block at any point after the add_executable or add_library section in your CMakeLists.txt, otherwise the ${APP_NAME} target will not be valid:

target_link_libraries(${APP_NAME} mylib)
get_target_property(mylib_INCLUDE_DIRS mylib INTERFACE_INCLUDE_DIRECTORIES)
target_include_directories(${APP_NAME}
    PRIVATE ${mylib_INCLUDE_DIRS}
)

Ensuring build order

If you need to ensure that the libraries you need to link are built before your application/library, then use add_dependencies.

For example, if your application depends on a library named "mylib", and you need to ensure that "mylib" is built before your application, then add the following line to your application CMakeLists.txt:

add_dependencies(${APP_NAME} mylib)

Linking Apple Frameworks

Linking to integrated frameworks

Linking to Apple frameworks is trivial. For example, if your Axmol project needs to link with the MediaPlayer, StoreKit and SafariServices, add this block at any point after the add_executable or add_library section in your CMakeLists.txt, otherwise the ${APP_NAME} target will not be valid:

target_link_libraries(${APP_NAME}
    "-framework MediaPlayer"
    "-framework StoreKit"
    "-framework SafariServices"
    )

Linking 3rd party xcframeworks

This is a little more involved.

As a practical example, let's say you wish to link to the Firebase SDK frameworks, and more specifically, Firebase Crashlytics. Refer to https://firebase.google.com/docs/ios/setup for more information.

The first thing is to add the framework to your project directory structure. For this example, the frameworks will exist in a sub-directory of your project named "thirdparty". So, Firebase SDK for iOS will be in the following path: [project_dir]/thirdparty/Firebase/ios]

You would extract the Firebase SDK into the folder above path. For Crashlytics, you would need both the Firebase Analytics and Firebase Crashlytis SDKs. You should see something like this in the thirdparty/Firebase/ios directory:

Add this macro to your CMakeLists.txt to make things a bit easier:

macro(ADD_XCFRAMEWORK fwname appname paths)
    #set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM BOTH)
    set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY BOTH)
    #set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE BOTH)
    find_library(FRAMEWORK_${fwname}
        NAMES ${fwname}
        PATHS ${paths}
        #PATH_SUFFIXES Frameworks
        NO_DEFAULT_PATH)
    if(${FRAMEWORK_${fwname}} STREQUAL FRAMEWORK_${fwname}-NOTFOUND)
        MESSAGE(ERROR ": Framework ${fwname} not found")
    else()
        TARGET_LINK_LIBRARIES(${appname} ${FRAMEWORK_${fwname}})
        MESSAGE(STATUS "Framework ${fwname} found at ${FRAMEWORK_${fwname}}")
    endif()
    #set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM ONLY)
    set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
    #set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
endmacro(ADD_XCFRAMEWORK)

Finally, to link the required frameworks to your application, add the following lines to link the required libraries:

ADD_XCFRAMEWORK(FBLPromises ${APP_NAME} "${CMAKE_SOURCE_DIR}/thirdparty/Firebase/ios/FirebaseAnalytics/")
ADD_XCFRAMEWORK(FirebaseAnalytics ${APP_NAME} "${CMAKE_SOURCE_DIR}/thirdparty/Firebase/ios/FirebaseAnalytics/")
ADD_XCFRAMEWORK(FirebaseCore ${APP_NAME} "${CMAKE_SOURCE_DIR}/thirdparty/Firebase/ios/FirebaseAnalytics/")
ADD_XCFRAMEWORK(FirebaseCoreInternal ${APP_NAME} "${CMAKE_SOURCE_DIR}/thirdparty/Firebase/ios/FirebaseAnalytics/")
ADD_XCFRAMEWORK(FirebaseInstallations ${APP_NAME} "${CMAKE_SOURCE_DIR}/thirdparty/Firebase/ios/FirebaseAnalytics/")
ADD_XCFRAMEWORK(GoogleAppMeasurement ${APP_NAME} "${CMAKE_SOURCE_DIR}/thirdparty/Firebase/ios/FirebaseAnalytics/")
ADD_XCFRAMEWORK(GoogleAppMeasurementIdentitySupport ${APP_NAME} "${CMAKE_SOURCE_DIR}/thirdparty/Firebase/ios/FirebaseAnalytics/")
ADD_XCFRAMEWORK(GoogleUtilities ${APP_NAME} "${CMAKE_SOURCE_DIR}/thirdparty/Firebase/ios/FirebaseAnalytics/")
ADD_XCFRAMEWORK(nanopb ${APP_NAME} "${CMAKE_SOURCE_DIR}/thirdparty/Firebase/ios/FirebaseAnalytics/")

ADD_XCFRAMEWORK(FirebaseCoreExtension ${APP_NAME} "${CMAKE_SOURCE_DIR}/thirdparty/Firebase/ios/FirebaseCrashlytics/")
ADD_XCFRAMEWORK(FirebaseCrashlytics ${APP_NAME} "${CMAKE_SOURCE_DIR}/thirdparty/Firebase/ios/FirebaseCrashlytics/")
ADD_XCFRAMEWORK(FirebaseSessions ${APP_NAME} "${CMAKE_SOURCE_DIR}/thirdparty/Firebase/ios/FirebaseCrashlytics/")
ADD_XCFRAMEWORK(GoogleDataTransport ${APP_NAME} "${CMAKE_SOURCE_DIR}/thirdparty/Firebase/ios/FirebaseCrashlytics/")

target_include_directories(${APP_NAME} PUBLIC ${CMAKE_CURRENT_LIST_DIR}/thirdparty/Firebase/ios)

The above example is not comprehensive, and depending on your requirements, you may need to link with more libraries, or less of them. Refer to the Firebase documentation for more details.

How to call 3rd party libraries or frameworks

Each library is different, and we can't provide answers for any of them. As a rule of thumb, it depends on the language of the library. If the library is written in:

• C / C++: please check the documentation of the library.
• Objective-C: there's interoperability between Obj-C and C++ by using Objective-Cpp files (.mm).
• Swift: check this Mixing Swift and C++ documentation.
• Java: you will have to write adapters using JNI. Also, please check these JNI tips.