<html>
<head>
<title>Xcode's Plugin Interface : Build Settings</title>
<link rel="stylesheet" href="doc.css" />
</head>
<body>
<h1>Xcode's Plugin Interface : Build Settings</h1>
<p>You'll find some official informations about build setting variables here :</p>
<ul>
<li><a href="http://developer.apple.com/documentation/DeveloperTools/Conceptual/XcodeUserGuide20/Contents/Resources/en.lproj/bs_build_settings/chapter_31_section_1.html">Apple's chapter about the build setting system</a></li>
<li><a href="http://developer.apple.com/documentation/DeveloperTools/Conceptual/XcodeUserGuide20/Contents/Resources/en.lproj/bs_build_settings/chapter_31_section_5.html">Build Setting Evaluation</a></li>
<li><a href="http://developer.apple.com/documentation/DeveloperTools/Conceptual/XcodeUserGuide20/Contents/Resources/en.lproj/bs_build_settings/chapter_31_section_8.html">Some build setting variables and their short description</a></li>
</ul>
<!-- --- --- --- --- -->
<h2>Table of Contents</h2>
<div class="toc">
<div class="toc1"><a href="index.html">UP</a> <small>(Xcode's Plugin Interface)</small></div>
<div class="toc1"><a href="#buildsettings">1. Adding Build Settings in the GUI (<code>.pbbsetspec</code>)</a></div>
<div class="toc1"><a href="#api">2. Environment API</a></div>
<div class="toc1"><a href="#variables">3. Useful Environment Variables</a></div>
</div>
<!-- --- --- --- --- -->
<h2><a name="buildsettings">1. Adding Build Settings in the GUI (<code>.pbbsetspec</code>)</a></h2>
<p>The GUI settings are defined either in a dedicated <code>.pbbsetspec</code> file or in the
specification file of a compiler (<code>.pbcompspec</code>) or a linker (<code>.pblinkspec</code>).
The explainations are illustrated with a compiler specification file.</p>
<p>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):</p>
<p class="object"><code><a href="file:///Developer/Library/PrivateFrameworks/DevToolsCore.framework/Resources/GCC.xcspec">/Developer/Library/PrivateFrameworks/DevToolsCore.framework/Resources/GCC.xcspec</a></code></p>
<p class="object"><code><a href="file:///Developer/Library/PrivateFrameworks/DevToolsCore.framework/Resources/Built-in%20linkers.pblinkspec">/Developer/Library/PrivateFrameworks/DevToolsCore.framework/Resources/Built-in linkers.pblinkspec</a></code></p>
<p class="object"><code><a href="file:///Developer/Library/PrivateFrameworks/DevToolsCore.framework/Resources/Built-in%20build%20settings.pbbsetspec">/Developer/Library/PrivateFrameworks/DevToolsCore.framework/Resources/Built-in build settings.pbbsetspec</a></code></p>
<p>The build settings are defined by a property list like the following one :</p>
<pre>(
{
Identifier = com.domain.me.compilers;
Name = "My compiler";
…
Options = (
{
<strong>// Bool options can have only two values : NO or YES.</strong>
Name = OPTION_1;
Type = bool;
DefaultValue = NO;
<strong>// You may define how an option must be translated to an argument(s) for the
// compiler compand line:</strong>
CommandLineArgs = {
NO = (); // expand to nothing
YES = ("-with-opt1") // expand to one argument : -with-opt1
};
Category = "My Category";
},
{
<strong>// A stringlist is a string containing many string value, separated by space,
// like command line arguments in shells.</strong>
Name = OPTION_2;
Type = stringlist; // replace with "pathlist" if the strings in the list are paths
UIType = ??; // not documented
DefaultValue = "";
<strong>// if the option value is «aa bb», Xcode will issue «-I aa -I bb» on the
// command line:</strong>
CommandLineArgs = ("-I", "$(value)");
<strong>// will appear after OPTION_1 in the build setting window:</strong>
AppearsAfter = OPTION_1;
<strong>// will appear after OPTION_3 on the command line:</strong>
AppearsOnCommandLineAfter = OPTION_3;
<strong>// will appear on the command if this value expands to YES:</strong>
CommandLineCondition = "$(OPTION_1)";
Category = "My Category"; // put option into this group
},
{
<strong>// A string.</strong>
Name = OPTION_3;
Type = string; // replace with "path" if the string represent a path
DefaultValue = "I'm the default string";
AvoidEmptyValue = YES; <strong>// Show the default value if the user put an empty value</strong>
CommandLineArgs = ("$(value)");
<strong>// option will appear on the command line args only for these architectures:</strong>
<strong>// (only works with compilers, no with linkers)</strong>
Architectures = (ppc, ppc64);
<strong>// option will appear on the command line args only for these source file types:</strong>
FileTypes = (sourcecode.me, sourcode.mebis);
Category = "My Other Category";
},
{
<strong>// Option with predefined choices.</strong>
Name = OPTION_4;
Type = enum;
AllowedValues = (VAL1, VAL2, VAL3, VAL4, VAL5);
DefaultValue = VAL3;
<strong>// in this case, $(value) will be VAL3 or VAL4 or VAL5:</strong>
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";
},
);
};</pre>
<p>The <code>CommandLineArgs</code> , <code>Architectures</code>, <code>FileTypes</code> keys are
only useful in compiler or linker specification.</p>
<p>If you don't set the <code>Category</code> key, the option won't appear in the GUI.</p>
<p>If you don't set the <code>CommandLineArgs</code> 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 <code>OPTION_1</code> with the following code :</p>
<pre>[context expandedValueForString:@"$(OPTION_1)"]</pre>
<p>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 !!!).</p>
<p>If you put the option definitions in a <code>.pbbsetspec</code>, you must define the
<code>specificationToShowInUserInterface</code> method of your compiler class to inform which
specification should be shown when your compiler is used:</p>
<pre>- (XCPropertyDomainSpecification*) specificationToShowInUserInterface
{
XCPropertyDomainSpecification* spec = [[XCPropertyDomainSpecification specificationRegistry] objectForKey:@"com.domain.buildsettings.mycomp"];
return (XCPropertyDomainSpecification*)[spec loadedSpecification];
}</pre>
<p>Be carefull : if you do this (using pbbsetspec files), command line arguments won't be
automatically issued.</p>
<p>The human readable names are defined in a <code>.strings</code> file (in order to be localizable)
named <code>«identifier».strings</code> (<code>com.domain.me.compilers.strings</code> for the above
sample):</p>
<pre>"[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]";</pre>
<!-- --- --- --- --- -->
<h2><a name="api">2. Environment API</a></h2>
<p>Expand variables :</p>
<ul>
<li>Expand as a string : <code>[PBXBuildSetting expandedValueForString:]</code></li>
<li>Expand as a path : <code>[PBXBuildSetting absoluteExpandedPathForString:]</code></li>
<li>Expand as a boolean value : <code>[PBXBuildSetting expandedBooleanValueForString:]</code> (Xcode >= 2.2)</li>
<li>Test if the variable expands to a non-empty string : <code>[PBXBuildSetting expandedValueIsNonEmptyForString:]</code> (Xcode >= 2.2)</li>
<li><strike>Find if there is a variable to expand : <code>[PBXBuildSetting expandedValueExistsForString:]</code></strike> (Xcode < 2.2)</li>
<li><strike>Expand a string : <code>[PBXBuildSetting expandedValueForString:getRecursiveSettingName:options:]</code><br />
(the two last parameters should be respectively <code>nil</code> and <code>1</code>)</strike> (Xcode < 2.2)</li>
</ul>
<p>Modify string variables :</p>
<ul>
<li>Set : <code>[PBXBuildSetting setStringValue:forDynamicSetting:]</code></li>
<li>Delete : <code>[PBXBuildSetting removeDynamicSetting:]</code></li>
</ul>
<p>Modify string list variables :</p>
<ul>
<li>Insert a string at the beginnig : <code>[PBXBuildSetting prependStringOrStringListValue:toDynamicSetting:]</code></li>
<li>Insert a string at the end : <code>[PBXBuildSetting appendStringOrStringListValue:toDynamicSetting:]</code></li>
<li>Remove an string from the list : <code>[PBXBuildSetting removeStringOrStringListValue:]</code></li>
</ul>
<p>Some useful tasks :</p>
<ul>
<li>Convert a string to a boolean value : <code>[NSString boolValue]</code></li>
<li>Convert a space separated string list to a string array : <code>[NSString arrayByParsingAsStringList]</code></li>
</ul>
<p>Compute command line arguments from build settings :</p>
<ul>
<li>Defined in the <code>Options</code> key :<br />
<code>[XCCommandLineToolSpecification commandLineForAutogeneratedOptionsInTargetBuildContext:]</code></li>
<li>Defined in a custom key :<br />
<code>[XCCommandLineToolSpecification commandLineForAutogeneratedOptionsForKey:inTargetBuildContext:]</code></li>
</ul>
<p>For more informations, see the <code>XCPBuildSystem.h</code>n <code>XCPSpecifications.h</code>
and <code>XCPSupport.h</code> header files available <a href="xcode-plugin-headers.zip">here</a>.</p>
<!-- --- --- --- --- -->
<h2><a name="variables">3. Useful Environment Variables</a></h2>
<p>In many case, it's possible to provide different values when compiling to different architectures
or different variant : <code>MYSETTING_ppc</code>, <code>MYSETTING_x86</code>,
<code>MYSETTING_normal</code>, <code>MYSETTING_debug</code>, <code>MYSETTING_normal_ppc</code>.</p>
<p>Variables containing useful paths :</p>
<ul>
<li>Local applications folder : <code>LOCAL_APPS_DIR</code> <small>(defaults to <code>/Applications</code>)</small></li>
<li>Local utilities folder : <code>LOCAL_ADMIN_APPS_DIR</code> <small>(defaults to <code>/Applications/Utilities</code>)</small></li>
<li>Local library folder : <code>LOCAL_LIBRARY_DIR</code> <small>(defaults to <code>/Library</code>)</small></li>
<li>User folder : <code>HOME</code> <small>(defaults to <code>~</code>)</small></li>
<li>User applications folder : <code>USER_APPS_DIR</code> <small>(defaults to <code>~/Applications</code>)</small></li>
<li>User library folder : <code>USER_LIBRARY_DIR</code> <small>(defaults to <code>~/Library</code>)</small></li>
<li>Developer folder : <code>DEVELOPER_DIR</code> <small>(defaults to <code>/Developer</code>)</small></li>
<li>Project base : <code>PROJECT_DIR</code></li>
<li>Target output folder (for final product) : <code>TARGET_BUILD_DIR</code> (or <code>BUILT_PRODUCTS_DIR</code>)</li>
<li>Project output folder (global for all targets) : <code>BUILD_ROOT</code> (or <code>BUILD_DIR</code>)</li>
<li>Target objects folder (for .o files) : <code>OBJECTS_DIR</code> (<code>OBJECT_FILE_DIR</code>, <code>OBJECT_FILE_DIR_$(variant)</code>, <code>$(OBJFILES_DIR_$(variant))/$(arch)</code>)</li>
<li>Target derived files folder (for yacc, lex output) : <code>DERIVED_FILES_DIR</code> (or <code>DERIVED_FILE_DIR</code> or <code>DERIVED_SOURCES_DIR</code>)</li>
<li>Temporary folder for one target : <code>TEMP_DIR</code></li>
<li>Temporary folder for the whole project : <code>PROJECT_TEMP_DIR</code></li>
<li>Temporary folder for the one configuration : <code>CONFIGURATION_TEMP_DIR</code></li>
</ul>
<p>Variables used to defined the product :</p>
<ul>
<li>Installation path : <code>INSTALL_PATH</code>. A good value is : <code>$(HOME)/bin</code> for
command line tools, <code>$(HOME)/Applications</code> for applications, <code>$(HOME)/Library/Frameworks</code> for frameworks…</li>
<li>Installation path for headers : <code>PUBLIC_HEADERS_FOLDER_PATH</code></li>
<li>Product name : <code>PRODUCT_NAME</code></li>
<li>Project file name : <code>PROJECT_NAME</code></li>
<li>Executable name : <code>EXECUTABLE_NAME</code>. A good value is :<br />
<code>$(EXECUTABLE_PREFIX)$(PRODUCT_NAME)$(EXECUTABLE_VARIANT_SUFFIX)$(EXECUTABLE_SUFFIX)</code>.</li>
<li>Architectures : <code>ARCHS</code> (see <code>arch</code>)</li>
<li>Build variants : <code>BUILD_VARIANTS</code> (see <code>variant</code>)</li>
</ul>
<p>Variables containing compilation/linking directives :</p>
<ul>
<li>Header paths : <code>HEADER_SEARCH_PATHS</code></li>
<li>Library paths : <code>LIBRARY_SEARCH_PATHS</code></li>
<li>Framework paths : <code>FRAMEWORK_SEARCH_PATHS</code></li>
<li>Should generate profiling code : <code>GENERATE_PROFILING_CODE</code></li>
<li>Type of libary : <code>LIBRARY_STYLE</code> (= <code>STATIC</code>, <code>DYNAMIC</code> or <code>BUNDLE</code>)</li>
</ul>
<p>Variables used in compiler specification files (Xcode >= 2.3) :</p>
<ul>
<li>Input file path : <code>InputFile</code></li>
<li>Output file path : <code>OutputFile</code></li>
<li>String added to ouput file name, if two source files have the same basename : <code>SourceBaseNameUniquefier</code></li>
<li>Output file destination : <code>ObjectsDir</code></li>
</ul>
<p>Variables used during dependency graph creation (lowercase) :</p>
<ul>
<li>Current variant being processed : <code>variant</code> (or <code>CURRENT_VARIANT</code>)</li>
<li>Current architecture being processed : <code>arch</code> (or <code>CURRENT_ARCH</code>)</li>
<li><strike>Object files sent to the linker : <code>object_files_$(variant)_$(arch)</code></strike>
(Xcode < 2.3)</li>
<li>Object files sent to the linker : <code>object_files</code> (Xcode >= 2.3)</li>
<li>?? : <code>non_master_object_files</code></li>
<li>?? : <code>dylib_files</code></li>
<li>?? : <code>sab_binaries</code></li>
<li>?? : <code>strippable_linked_product_$(variant)</code></li>
<li>File specific build flags : <code>build_file_compiler_flags</code></li>
<li>?? : <code>build_file_attributes</code></li>
<li>Force to use the given linker : <code>compiler_mandated_linker</code> and <code>compiler_mandated_linker_priority</code>
(use a custom product specification or <code>RequiredLinker</code> instead)</li>
<li>?? : <code>compiler_mandated_librarian</code> and <code>compiler_mandated_librarian_priority</code></li>
</ul>
<p>Other available variables :</p>
<ul>
<li>Current configuration : <code>CONFIGURATION</code> (or <code>BUILD_STYLE</code>)</li>
<li>Current user ID : <code>UID</code></li>
<li>Current user name : <code>USER</code></li>
<li>Current user group : <code>GROUP</code></li>
<li>Current action : <code>BUILD_ACTION</code></li>
<li>Previous definition : <code>inherited</code></li>
</ul>
<!-- --- --- --- --- -->
<p class="footer">
Copyright © 2005-2006 Damien Bobillot,
E-Mail : <a href="mailto:damien.bobillot.2002_xcodeplugin CHEZ m4x.org?Subject=%5BXcode Plugins%5D%20">damien.bobillot.2002_xcodeplugin CHEZ m4x.org</a>
</p>
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
_uacct = "UA-445657-1";
urchinTracker();
</script>
</body>
</html>
