Change the search path in the Xcode project with the configuration settings file

Depending on your application requirements, you might require an SDK or software beyond your control. Although the SDK’s installation path tends to be consistent, it could vary based on the machine or the developer’s preferences.

In such cases, if you set the search path directly to the project file, you must change the search path to match your settings each time you pull the project file from Git. Conversely, when you commit, you must remind yourself not to include the project file.

This article explains how to avoid the situations above.

Create the configuration settings file

The reason for these problems is that the project file’s value depends on the environment. To avoid this problem, create the configuration settings file on each environment and define the value of configurations in it.

For further information on creating and assigning the configuration settings file, refer to the following article.

あわせて読みたい

How To Create the Xcode Configuration Settings File The Xcode project configuration is saved in the project file (*.xcodeproj). It is enough for normal-scale application development, but if you develop a middl…

Refer to the above article and create the following thee configuration settings files.

• Debug.xcconfig
• Release.xcconfig
• SearchPath.xcconfig
  

The role of each file is suggested by its name. Debug.xcconfig for the debug build and Release.xcconfig for the release build. Write the following code into the Debug.xcconfig and the Release.xcconfig files.

#include "SearchPath.xcconfig"

Configure the search path

For developing iOS and macOS apps, the following three configurations are generally used for the search paths.

• Framework Search Paths
• Header Search Paths
• Library Search Paths

These configurations are in Search Paths in the build settings.

Framework Search Paths

The framework search paths are directories where the linker searches the frameworks when linked to the framework.

Header Search Paths

The header search paths are directories where the compiler searches the header files, including header files in C/C++ or Objective-C/C++ code.

Library Search Paths

The library search paths are directories where the linker searches the libraries when linked to the library.

Configure with the configuration settings file

Use the following configurations to configure the search paths with the configuration settings file.

The search path can be multiple directories. Each directory is separated with spaces. If the directory path contains spaces, surround it with a quote.

In this article, we write the search paths in the SearchPath.xcconfig file. For example, write as follows.

FRAMEWORK_SEARCH_PATHS = /usr/local/share/mydevice-sdk/frameworks $(inherited)
HEADER_SEARCH_PATHS = /usr/local/share/mydevice-sdk/includes $(inherited)
LIBRARY_SEARCH_PATHS = /usr/local/share/mydevice-sdk/libs $(inherited)

You can use $(inherited) to use the default and inherited values from higher.

In the above example, because we write the configurations before $(inherited), the paths in the configuration settings file are prioritized over the inherited directories. In this example, we assume to use the device SDK. Of course, it is better not to duplicate the file, but the SDK may provide a file with the same name as the one included in standard header files. It may also be customized specifically for the SDK. In that case, the SDK should be used first, so the SDK side is given priority.

Don’t manage with Git

This alone does not make it machine-specific; the SearchPath.xcconfig file is expected to differ for each machine. To do this, write SearchPath.xcconfig in .gitignore and remove it from Git’s control.

Doing this allows you to create the SearchPath.xcconfig in each local repository.

However, this method, which mandates creation, is less robust due to potential issues when integrating with CI (Continuous Integration).

What about files for CI?

If we need to create SearchPath.xcconfig for each environment cloned from Git, it may be a trouble when integrated with CI (Continuous Integration).

The last configuration setting is used when the same configuration settings are defined multiple. You can define the default value by using this behavior. Do as follows.

#include "SearchPath-default.xcconfig"
#include? "SearchPath.xcconfig"

Now we can’t make you create SearchPath.xcconfig, but locally, by making SearchPath.xcconfig, you can override the search paths in the SearchPath-default.xcconfig.

In the SearchPath.xccofig, we use #include?. The include statement has the suffix ?. If you use #include? to include the other configuration file, the Xcode doesn’t say error when the file is missing. This is because Xcode only includes files if available.

You can build without creating SearchPath.xccofig if not needed, and you can override configuration settings when the SDK is located in a different directory.

Switch the libraries and headers for debugging or release

You should switch the libraries and headers between debugging and release stages. For example, when the SDK presents debug build and release build libraries.

Create separate SearchPath.xcconfig files for each debug and release. For example, you might name these files as follows.

• SearchPath-debug.xcconfig
• SearchPath-release.xcconfig
  

Include the SearchPath-debug.xcconfig file from the Debug.xcconfig file.

#include "SearchPath-debug.xcconfig"

Include the SearchPath-release.xcconfig file from the Release.xcconfig file.

#include "SearchPath-release.xcconfig"

Open the build settings in Xcode, and you’ll see that the search paths for debug and release are set as expected.