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.

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.

Search Paths
Search Paths

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.

Search PathConfiguration
The framework search path FRAMEWORK_SEARCH_PATHS
The header search path HEADER_SEARCH_PATHS
The library search path LIBRARY_SEARCH_PATHS
Configurations for search paths

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.

Create the “SearchPath-default.xcconfig”.
Write the default values into the “SearchPath-default.xcconfig”.

CI/CD uses this value.

Write the following code into the “Debug.xcconfig” and “Release.xcconfig” to read “SearchPath.xcconfig” after “SearchPath-default.xcconfig”.
#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.

Search Path
Search Path


Authored Books

  • URLをコピーしました!
  • URLをコピーしました!


Akira Hayashi (林 晃)のアバター Akira Hayashi (林 晃) Representative(代表), Software Engineer(ソフトウェアエンジニア)

アールケー開発代表。Appleプラットフォーム向けの開発を専門としているソフトウェアエンジニア。ソフトウェアの受託開発、技術書執筆、技術指導・セミナー講師。note, Medium, LinkedIn
Representative of RK Kaihatsu. Software Engineer Specializing in Development for the Apple Platform. Specializing in contract software development, technical writing, and serving as a tech workshop lecturer. note, Medium, LinkedIn