Xcode's Plugin Interface : Compilers & Linkers

Everything starts when Xcode loads your plugin bundle, just after you launch it. Xcode looks at the content of the Info.plist file to initialize your plugin, and read all *.pb*spec or .xcspec files of your plugin Resources folder. At this time, Xcode don't execute any code, except if you add a NSPrincipalClass entry in the Info.plist file, it just stores informations about what provide your plugin.

The second phase, the most important one, is the dependency graph creation. It appends every time you open a project, add/remove files to/from a project, modify some build settings… It's the phase where your plugin code is run.

Your code must create one XCDependencyNode for each file involved in the compilation (source file, object files, final or product files), and add dependency relations between each nodes. Some of these nodes will be marked as "product nodes" by calling addProductNode:, nodes representing a file of your final product. Nodes are identified by a name which is, by convention, the POSIX path of the corresponding file.

The last phase is the real compilation/linking of files, the building phase. Here, Xcode read the dependency graph and run the command only if they are needed (i.e. if the output file doesn't exist or if the input files have been modified since last compilation) and in an best order that satisfy the dependencies.

(only for Xcode 2.1) During the building phase, Xcode create .dot files describing the dependency graph after and before running the commands (you'll find them in build/�project�.build/�configuration�/�target�.build/). You need the Graphviz application to view them. These .dot files are very useful to check if your code create the good dependency graph.

2. Graph Creation API

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

3. Compiler Sample Code (.pbcompspec)

First solution : no code, less generic

I've never tried this solution myself, and, according to people trying to use it, it doesn't work. It's here for the case where you've more chance than others ;).

Starting with Xcode version 2.3, it's possible to integrate a compiler, without writing any code. All you have to do is to write a mycompiler.pbcompspec file with the following format�:

{
    Identifier = com.domain.me.compiler;
    Class = MyCompilerSpecification;        // optional
    CommandInvocationClass = MyToolInvocation; // optional
    Name = "My Compiler";
    Description = "My source compiler";
    Version = "Default";                    // optional
    Vendor = "Me";                          // optional
    Architectures = ("ppc","i386");         // optional
    IsArchitectureNeutral = No;				// optional (if "Yes", "Architectures" is useless)
    Languages = (mytype);                   // optional
    FileTypes = (sourcecode.mytype);
    ExecPath = "/usr/local/bin/mycompiler";
    RuleName = ( "ProcessingXXX", "$(OutputFile)", "$(InputFile)" );
    OutputFileSuffix = ".o";
    RequiredLinker = com.domain.me.linker;  // optional (linker that must be used if using this
                                            // compiler for at least one source file)
    RequiredLibrarian = ??;                 // optional
    CommandOutputParser = (…);              // optional
    PatternsOfFlagsNotAffectingPrecomps = (…) // optional
    OptionsForCommandLine = (…);            // optional
    Options = {
        {   Name = Input;
            Type = stringlist;
            CommandLineArgs = ( "$(value)" );
            InputDependencies = "$(Input)"; // add to list of files needed before running the compiler
            IsCommandInput = YES;
        },
        {   Name = Output;
            Type = stringlist;
            CommandLineArgs = ( "-o", "$(value)" );
            OutputDependencies = "$(Output)"; // add to list of files created by the compiler
            IsCommandOutput = YES;
        },
        {   Name = "build_file_compiler_flags"; // compiler flags specific to this source file 
        	Type = stringlist;
            CommandLineArgs = { "" = ();  "<<otherwise>>" = ( "$(value)" ); };
        }
        …                                   // see here for more details on options
    };
    OptionCategories = {…};                 // optional (see here)
}

As you can see, Xcode creates to new environment variables $(OutputFile) and $(InputFile). The output file path is derived from the input path by replacing the extension with the value of the OutputFileSuffix key.

Second solution : with Objective-C code, more generic

If the first solution don't allow you to do what you want, you need to write a custom compiler specification class (inheriting from XCCompilerSpecification). In this case you need to add the Class key, but RuleName, OutputFileSuffix, OutputFileSuffix are not required. You also don't need to use the InputFile, OutputFile and build_file_compiler_flags options.

Xcode's Plugin Interface : Compilers & Linkers

Table of Contents

1. Xcode's Build System

2. Graph Creation API

3. Compiler Sample Code (`.pbcompspec`)

First solution : no code, less generic

Second solution : with Objective-C code, more generic

4. Linker Sample Code (`.pblinkspec`)

5. Parsing the ouput of command line tools

6. Product Type Sample Code (`.pbprodspec`)

Xcode's Plugin Interface : Compilers & Linkers

Table of Contents

1. Xcode's Build System

2. Graph Creation API

3. Compiler Sample Code (.pbcompspec)

First solution : no code, less generic

Second solution : with Objective-C code, more generic

4. Linker Sample Code (.pblinkspec)

5. Parsing the ouput of command line tools

6. Product Type Sample Code (.pbprodspec)

3. Compiler Sample Code (`.pbcompspec`)

4. Linker Sample Code (`.pblinkspec`)

6. Product Type Sample Code (`.pbprodspec`)