Xcode's Plugin Interface : Specification Files

Table of Contents

1. Generic Informations about Specification Files

These files are in fact property lists, and often use the ASCII format. However, if you wish, you may use the XML or binary formats for property lists.

In each .pb«thing»spec file, you have an array of specifications of type «thing».

Sample file containing two specifications :

(
    {
        Identifier = com.domain.myxcodeplugin.spec1;
        Name = "Spec 1";              // there's a space, so quotes are required
        Class = MyOwnObjectiveCClass; // there's no space, so quotes are not required
    },
    {
        Identifier = com.domain.myxcodeplugin.spec2;
        BasedOn = com.domain.myxcodeplugin.spec1;
        «AList» = ("aaa","bbb");
        «ABoolean» = YES;    // or NO
    },
)

The generic properties, used in every kind of specification, are :

• Identifier (string) : a unique identifier, usually in inverted DNS format.
• BasedOn (string) : inherit all properties of the given specification.
• Class (string) : name of an Objective-C class used when instantiating this specification.
• Name (string) : a human readable short name used for Xcode's user interface.
• Description (string) : a description of the specification.

2. File Type Definition (.pbfilespec)

You'll find sample files here :

/Developer/Library/PrivateFrameworks/DevToolsCore.framework/Resources/Built-in file types.pbfilespec

/Developer/Library/PrivateFrameworks/DevToolsCore.framework/Resources/Standard file types.pbfilespec

Specific properties of file type definitions used for identification (Xcode run all these tests to find the type of a file) :

• MIMETypes (array of strings) : MIME types like "text/html".
• Extensions (array of strings) : file extensions like "mp3". "" may be used to match files without any extension.
• TypeCodes (array of strings or data) : Classic's four-char-code types like "TEXT" or "PICT".
• FilenamePatterns (array of strings) : regular expression like "[mM]akefile".
• MagicWord (array of strings or data) : first bytes of the file like "<?xml" or <CAFEBABE>
• Prefix (array of strings) : list of prefixes allowed for this kind of file
• Permissions (string) : set to "executable" if this kind of file must be executable.

Specific properties of file type definitions describing content :

• ComputerLanguage (string) : the identifier of the language used for syntax coloring (see .pblangspec files). (Xcode < 3.0)
• Language (string) : the identifier of the language used for syntax coloring (see .xclangspec files). (Xcode > 3.0)
• ContainsNativeCode (bool) : set if file contains native code.
• RequiresHardTabs (bool) : used for files like Makefiles where tabulations must not be converted to spaces.
• IsApplication, IsBundle, IsDynamicLibrary, IsExecutable, IsExecutableWithGUI, IsFrameworkWrapper, IsStaticFrameworkWrapper, IsStaticLibrary, IsTextFile, IsSourceCode, IsFolder, IsWrapperFolder, IsProjectWrapper, IsDocumentation, IsBuildPropertiesFile (bools) : to allow specific treatment by Xcode.
• IsTargetWrapper (bool) : TODO.
• IsTransparent (bool) : for folders, can the user go inside ? (?)

Specific properties of file type definitions used for building :

• AppliesToBuildRules (bool) : can be added to the source build phase (for compilable files).
• IsScannedForIncludes (bool) : should Xcode search for #include or similar inclusion command ?
• ChangesCauseDependencyGraphInvalidation (bool) : if file is modified, it will be recompiled.
• FallbackAutoroutingBuildPhase (bool) : TODO.
• IncludeInIndex (bool) : TODO.
• GccDialectName : TODO.
• CanSetIncludeInIndex (bool) : TODO.

Specific properties of file type definitions used for wrappers :

• ExtraPropertyNames (dictionary) : see samples
• ComponentParts (dictionary) : see samples

3. Language Definition (.pblangspec)

You'll find a sample file here :

/Developer/Library/PrivateFrameworks/DevToolsCore.framework/Resources/Built-in languages.pblangspec

A language specification describes the syntax of a language (for syntax coloring), how it should be indent (for automatical indentation - not documented) and other things like included files or function name extracting (for the function popup - not documented).

A sample specification :

(
    {
        Identifier = mylang;
        Name = "My Language";
        Description = "My Language"; // may be longer
        BasedOn = "pbx_root_language";
        SourceScannerClassName = MySourceScanner;
            // (optionnal) name of an Objective-C class inheriting from PBXSourceScanner
        SupportsIndentation = NO;   // only work for C-like languages
        Indentation = {}            // indentation definition (not documented)
        SyntaxColoring = {          // syntax definition (see next paragraph)
            «prop» = «value»;
            …
        }
    }
)

Now, the interesting part : how to define a language syntax. The syntax is not defined by a real user grammar like in other IDEs, but by a generic grammar implemented inside Xcode, with many parameters modifiable in the language specification. Theses parameters are :

• CaseSensitive (bool) : is the language case sensitive ?
• UnicodeSymbols (bool) : does the language allow unicode characters ?
• UnicodeEscapes (bool) : accept \uXXXX anywhere in a file, and return a single character (not yet supported).
• MultiLineComment (array of two-element arrays of strings): delimiter of multiline comments like ( ("/*","*/"), ("(*","*)") ).
• CommentsCanBeNested (bool) : YES if multiline comments may be nested (not implemented).
• SingleLineComment (array of strings) : beginning delimiter of a single line comment (the comment stops at the next newline character).
• FortranStyleComments (bool) : allow fortran comments.
• DocComment (string) : characters identifying a documentation comment, just after the comment start delimiter.
• String (array of two-element arrays of strings) : delimiters of a string like ( ("\"","\"") ) for "hello".
• Character (array of two-element arrays of strings) : delimiters of a character constant like ( ("'","'") ) for 'h'.
• EscapeCharacter (string of only one character) : the escape caracter for string and character constants.
• IdentifierStartChars (string) : allowed characters for the first character of an identifier.
• IdentifierChars (string) : allowed characters for other characters of an identifier.
• Keywords (array of strings) : language keywords.
• AltKeywords (array of strings) : non official keywords.
• DocCommentKeywords (array of strings) : keywords in documentation comments.
• PreprocessorKeywordStart (string of only one character): the first caracter of all preprocessor keywords.
• PreprocessorKeywords (array of strings) : preprocessor keywords (without PreprocessorKeywordStart).
• KeywordDelimeters (not yet implemented).
• IndexedSymbols (bool) : TODO.
• LinkStartChars, LinkPrefixChars, MailLocalNameDelimiter, DomainNameStartChars, DomainNameChars, URLSchemeDelimiter, URLLocationChars, URLSchemes : URL coloring.

4. Build Rules (.xcbuildrules)

This specification is used to informe Xcode which compiler it must use for a given file type.

(
    {
        Name = "ME source rule";
        FileType = "sourcecode.me";
        CompilerSpec = "com.domain.me.compilers.";
    },
)

5. Installing Your own Specification File

There's two possibilities :

• if you are writing a plugin, add your specification files in myXcodePlugin.pbplugin/Contents/Resources/.
• if you use Xcode 2.x, add it to ~/Library/Application Support/Apple/Developer Tools/Specifications/.
• if you use Xcode 3.x, add it to ~/Library/Application Support/Developer/Shared/Xcode/Specifications/.
• if you are still using Project Builder, it may have to put them in
  /Developer/Project Builder Extras/Specifications.

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