Xcode's Plugin Interface : Build Settings

You'll find some official informations about build setting variables here :

Table of Contents

UP (Xcode's Plugin Interface)
1. Adding Build Settings in the GUI (.pbbsetspec)
2. Environment API
3. Useful Environment Variables

1. Adding Build Settings in the GUI (.pbbsetspec)

The GUI settings are defined either in a dedicated .pbbsetspec file or in the specification file of a compiler (.pbcompspec) or a linker (.pblinkspec). The explainations are illustrated with a compiler specification file.

Some sample compiler/linker definitions with GUI build settings (the syntax may be slightly different from the one defined below because there're several equivalent syntaxes to define options):

/Developer/Library/PrivateFrameworks/DevToolsCore.framework/Resources/GCC.xcspec

/Developer/Library/PrivateFrameworks/DevToolsCore.framework/Resources/Built-in linkers.pblinkspec

/Developer/Library/PrivateFrameworks/DevToolsCore.framework/Resources/Built-in build settings.pbbsetspec

The build settings are defined by a property list like the following one :

(
    {
        Identifier = com.domain.me.compilers;
        Name = "My compiler";
        …
        Options = (
            {
                // Bool options can have only two values : NO or YES.
                Name = OPTION_1;
                Type = bool;
                DefaultValue = NO;
                // You may define how an option must be translated to an argument(s) for the
                // compiler compand line:
                CommandLineArgs = {
                    NO = ();                // expand to nothing
                    YES = ("-with-opt1")    // expand to one argument : -with-opt1
                };
                Category = "My Category";
            },
            {
                // A stringlist is a string containing many string value, separated by space,
                // like command line arguments in shells.
                Name = OPTION_2;
                Type = stringlist;  // replace with "pathlist" if the strings in the list are paths
                UIType = ??;        // not documented
                DefaultValue = "";
                // if the option value is «aa bb», Xcode will issue «-I aa -I bb» on the
                // command line:
                CommandLineArgs = ("-I", "$(value)");
                // will appear after OPTION_1 in the build setting window:
                AppearsAfter = OPTION_1;
                // will appear after OPTION_3 on the command line:
                AppearsOnCommandLineAfter = OPTION_3;
                // will appear on the command if this value expands to YES:
                CommandLineCondition = "$(OPTION_1)";
                Category = "My Category";   // put option into this group
            },
            {
                // A string.
                Name = OPTION_3;
                Type = string;      // replace with "path" if the string represent a path
                DefaultValue = "I'm the default string";
                AvoidEmptyValue = YES; // Show the default value if the user put an empty value
                CommandLineArgs = ("$(value)");
                // option will appear on the command line args only for these architectures:
                // (only works with compilers, no with linkers)
                Architectures = (ppc, ppc64);
                // option will appear on the command line args only for these source file types:
                FileTypes = (sourcecode.me, sourcode.mebis);
                Category = "My Other Category";
            },
            {
                // Option with predefined choices.
                Name = OPTION_4;
                Type = enum;
                AllowedValues = (VAL1, VAL2, VAL3, VAL4, VAL5);
                DefaultValue = VAL3;
                // in this case, $(value) will be VAL3 or VAL4 or VAL5:
                CommandLineArgs = { VAL1 = (-a); VAL2 = (-b); "<<otherwise>>" = (-custom, "$(value)") };
                Category = "My Other Category";
                CommonOption = YES; // ??
                AdditionalArgsForFixBundlizing = (…); // ??
                AdditionalLinkerArgs = (…); // ??
            },
        );
        OptionCategories = (
            {   Name = "My Category";
                IconName = "PBX-option-build";
                    // or PBX-option-warning PBX-option-language-c PBX-option-language-r
            },
            {   Name = "My Other Category";
                IconName = "PBX-option-build";
            },
        );
    };

The CommandLineArgs , Architectures, FileTypes keys are only useful in compiler or linker specification.

If you don't set the Category key, the option won't appear in the GUI.

If you don't set the CommandLineArgs key, the option won't be automatically translated into command line arguments. However, you may treat it in your plugin code (for instance to do custom stuff) : all options are added to the build environment. You may get the value of the option OPTION_1 with the following code :

[context expandedValueForString:@"$(OPTION_1)"]

In Xcode 2.0 to 2.2, the build settings defined in the specification of all used compiler/linker will be added to the GUI target inspector. In Xcode 2.3 and later, only settings of used compilers will be shown, and not those of used linkers :-( (it's really annoying !!!).

If you put the option definitions in a .pbbsetspec, you must define the specificationToShowInUserInterface method of your compiler class to inform which specification should be shown when your compiler is used:

- (XCPropertyDomainSpecification*) specificationToShowInUserInterface
{
    XCPropertyDomainSpecification* spec = [[XCPropertyDomainSpecification specificationRegistry] objectForKey:@"com.domain.buildsettings.mycomp"];
    return (XCPropertyDomainSpecification*)[spec loadedSpecification];
}

Be carefull : if you do this (using pbbsetspec files), command line arguments won't be automatically issued.

The human readable names are defined in a .strings file (in order to be localizable) named «identifier».strings (com.domain.me.compilers.strings for the above sample):

"[OPTION_1]-name" = "Option 1";
"[OPTION_1]-description" = "Description… [OPTION_1, -with-opt1]";

"[OPTION_2]-name" = "Option 2";
"[OPTION_2]-description" = "Description… [OPTION_2, -I]";

"[OPTION_3]-name" = "Option 3";
"[OPTION_3]-description" = "Description… [OPTION_3]";

"[OPTION_4]-name" = "Option 4";
"[OPTION_4]-value-[VAL1]" = "Value 1";
"[OPTION_4]-value-[VAL2]" = "Value 2";
"[OPTION_4]-value-[VAL3]" = "Value 3";
"[OPTION_4]-value-[VAL4]" = "Value 4";
"[OPTION_4]-value-[VAL5]" = "Value 5";
"[OPTION_4]-description" = "Description… [OPTION_4, -a, -b, -custom]";

2. Environment API

Expand variables :

Modify string variables :

Modify string list variables :

Some useful tasks :

Compute command line arguments from build settings :

For more informations, see the XCPBuildSystem.hn XCPSpecifications.h and XCPSupport.h header files available here.

3. Useful Environment Variables

In many case, it's possible to provide different values when compiling to different architectures or different variant : MYSETTING_ppc, MYSETTING_x86, MYSETTING_normal, MYSETTING_debug, MYSETTING_normal_ppc.

Variables containing useful paths :

Variables used to defined the product :

Variables containing compilation/linking directives :

Variables used in compiler specification files (Xcode >= 2.3) :

Variables used during dependency graph creation (lowercase) :

Other available variables :

Copyright © 2005-2015 Damien Bobillot, E-Mail : damien.bobillot.2002_xcodeplugin CHEZ m4x.org