Using a .xcconfig file

Guides | Tutorial By 5 years ago

In Xcode the build settings screen can be pretty daunting for some people, especially when you start iOS/Mac development. Knowing which settings to pick can be tricky, but I still see a lot of people that do this individually for each of their projects, which makes it easy to miss crucial build parameters you don’t want to distribute your app without. Using a .xcconfig file is extremely useful for solving this problem, it is a type of file for determining build parameters, meaning you can have this file sitting in one spot and have each of your projects referencing it. If you need to make a build setting change to all your projects, you can just add it to this one file and the next time you compile each of the projects the change will be taken into account.

The file is key value based, each value determining what the build settings for that key is. If you have seen one of these files before you may have been even more confused than the original build settings screen, but its actually quite the contrary, even if you don’t know any/all of the build setting keys (or values) you can easily create and maintain a .xcconfig file without any problems. In fact even a monkey could do it.

Start by opening the project you want to create a .xcconfig file for and add a new file. In the dialog that pops up select the Configurations Settings File. In the next screen give it a name and make sure the targets checkboxes are all unchecked, you don’t want to include this in your app’s bundle.

Now go to your project’s info screen, under the configurations section expand the list until your find the target you want your scheme to apply to, then select it from the drop down box.

In your target’s build settings check the ‘levels’ option, now you can see a list of all configurations, from default on the right all the way over to what the compiled setting will be on the left. Anything on the left will override the setting on the right. Xcode highlights the one that will actually be used in green.

Look for a build setting you want to add to your .xcconfig file in the build settings list, set it to the value you want it to be, then select that row, hit Command + C to copy, then push delete to get rid of your setting. I will use the iOS deployment target as an example. Go into your .xcconfig file and paste the contents of your clipboard. You will notice that you copied the key and value.

Now if you go back into your build settings you will see the config file’s column and value for your new build setting.

Continue doing this until you have filled your .xcconfig file with all the build settings you need. Now you can just import this one file into all your projects and link it up to your target(s).

  • aldousd

    Thanks for the great explain! I knew in principle that this was how this worked, (I’m a former visual studio developer,) but I very much appreciate the walkthrough. Is this a way that I can include different urls/keys for different targets? For example, one for Test, with the test URLs, one for QA with the QA urls, etc? Do those go directly into these config files or do I use flags set by these as keys for conditional compilation?

    • Tom

      I usually put these as conditionals in source, though you will want to setup a define macro in each of your targets so you know which target you are building for.

      For this you can have your base xcconfig file and then make a new one for each of your targets with just a single macro, then #include the base config file to inherit its settings, this way you don’t need to repeat the same config info across each file.

      Something like:

      #include “Config.xcconfig”

      Then in your source:

      #if QA_BUILD
      NSString* apiUrlString = @””;
      #elif TEST_BUILD
      NSString* apiUrlString = @””;

      • 余猛

        Hao to read xcconfig in my code!

        eg: my xcconfig write LOGIN_LOGO = lg_logo_renfu

        I want to get the value of LOGIN_LOGO ,hao to get!