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

Depending on the application you are developing, you may need an SDK or other software that you do not control, and while the installation path for the SDK will often be roughly the same, if it can be placed in an arbitrary location, the machine or developer may have different locations for it.

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

This article how to avoid above situations.


Create the configuration settings file

The reason of these problem is the value of the project file to be depending on the environment. To avoid this problem, create the configuration settings file on each environment and define the value of configurations in it.

For more information about how to create and assign the configuration settings file, see following article.

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

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

The role of the files are name implies. Debug.xcconfig for the debug build and Release.xcconfig for the release build. Write the following code into the Debug.xcconfig file and the Release.xcconfig file.

#include "SearchPath.xcconfig"

Configure the search path

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

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

These configurations are in Search Paths in build settings.

Search Paths
Search Paths

Framework Search Paths

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

Header Search Paths

The header search paths are directories where the compiler search the header files when include header files in C/C++ or Objective-C/C++ code.

Library Search Paths

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

Configure with the configuration settings file

To configure the search paths with configuration settings file, use following configurations.

Search PathConfiguration
The framework search pathFRAMEWORK_SEARCH_PATHS
The header search pathHEADER_SEARCH_PATHS
The library search pathLIBRARY_SEARCH_PATHS
Configurations for search paths

The search path can be multiple directories, the each directories are separated with spaces. If the directory path contains spaces, surround with quote.

In this article, 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 should use $(inherited) to use the default values and the inherited values from higher.

Above example, because write the configurations before $(inherited), the paths in the configuration settings file are used prior than inherited directories. In this example, we assume use the device SDK. It is better not to duplicate the file, but the SDK may provide a file with the same name as the header file that is included by default. 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 will not make it machine-specific; the SearchPath.xcconfig file is assumed to be different for each machine. To do this, write SearchPath.xcconfig in .gitignore and remove it from Git’s control.

By doing as this, you force create the SearchPath.xcconfig in each local repositories.

However, this method of forcing creation has the weakness that it is problematic in combination 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 trouble with when integrated with CI (Continuous Integration).

When the same configuration settings are defined mulitply, the last configuration setting is used. 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 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 force make you to create SearchPath.xcconfig, but in local, 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 suffix ?. If you use #include? to include the other configuration file, the Xcode doesn’t say error when the file is missing. Xcode only include file if available.

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

Switch the libraries and headers for debug or release

You may like to switch the libraries and headers for debug or release. For example, when the SDK presents both debug build and release build libraries.

Create the SearchPath.xccofing for each debug and release. For example, their file name to be following.

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

Includes the SearchPath-debug.xcconfig in Debug.xcconfig only.

#include "SearchPath-debug.xcconfig"

Includes the SearchPath-release.xcconfig in Release.xcconfig only.

#include "SearchPath-release.xcconfig"

Open the build settings in Xcode, you can see the search path for debug and release are actually set as expected.

Search Path
Search Path
Let's share this post !

Author of this article

Akira Hayashiのアバター Akira Hayashi Representative, Software Engineer

I am an application developer loves programming. This blog is a tech blog, its articles are learning notes. In my work, I mainly focus on desktop and mobile application development, but I also write technical books and teach seminars. The websites of my work and books are here -> RK Kaihatsu.