Creating and using Clang plugin with Xcode

Creating and using Clang plugin with Xcode

This tutorial describes how to create Clang plugin and covers the next things:

  • environment setup
  • basic plugin setup
  • setup Xcode project for plugin development
  • warnings reporting
  • errors reporting
  • Xcode integration
  • interactive hints for errors/warnings riddance


Clang Rocks!!!You can find the plugin here.


While working on BloodMagic, I realised that it’d be nice to have a tool for checking semantic errors related to BM usage. For example: in the interface property marked as lazy, but not defined as @dynamic in the implementation, or property marked as lazy, but class container doesn’t support injections.I concluded that I need to work with and I need a full-featured parser.I’ve tried different approaches: flex+bison, libclang, but ultimately I decided to write a Clang plugin.Just for testing purposes I’ve started a simple plugin with the following goals:
  • use Xcode for development
  • integrate ready plugin into Xcode and use it workaday
  • plugin should report warnings, errors and propose interactive hints for fixes (via Xcode UI)
Features of the test plugin:
  • report warning in case of class’ name starts with lowercase letter
  • report error in case of class’ name contains underscore _
  • propose hints for fixes

Environment setup

For plugin development we need llvm/clang, built from sourceCurrent clang version on my system – 3.3.1, so let’s build respective version:

Basic plugin setup

Create directory for pluginOur plugin based on example from Clang repo and here is it’s structure:We’ll use one source file for simplificationNow we’re able to generate Xcode-project, based on CMakeLists.txtRun ALL_BUILD target, and you’ll see dynamic library at lib/Debug/ToyCLangPlugin.dylib.


Clang AST module provides RecursiveASTVisitor, which allows us to traverse via AST. We just need to create a subclass and implement interesting methods. For test we’ll print all the found class names.Let’s create test source file and check how plugin works.Rebuild plugin and runWe’ll see a huge list of classes.

Report warnings

Let’s report warning in case if class’ name starts with lowercase letterAdd ASTContext to ToyClassVisitorAdd checkAdd some class with “bad” namerebuild and run

Report error

Let’s generate error in case of class’ name contains _Output after runningUncomment first check checkForLowercasedName and you’ll see both error and warning in the output

Xcode integration

Unfortunately, system (under ‘system’ I mean Xcode’s clang) clang doesn’t support plugins, so we need to hack Xcode a bit, to allow using of custom compiler.Unzip this archive and run following commands:This will enable custom compiler for Xcode.Reopen Xcode and you’ll see new compiler:custom_compilerCreate new project and select newly added custom clang in Build settingsTo enable plugin add following parameters to the OTHER_CFLAGS sectionOTHER_CFLAGSNote, that we use -add-plugin here, because we want to add our ASTAction, not to replace the existingAlso, you should disable modules for this target/builddisable_modulesAdd test.m to this project, or create new one, with class names that match plugin criteriaAfter build you’ll see error and warnings in a more familiar formerror_warning

Interactive hints

It’s time to add FixItHints for both warning and errorRebuild plugin and try to build test projectwarning_fixit_hint error_fixit_hint


As you can see, creating a clang plugin is relatively simple, but it needs some dirty hacks with Xcode, and you should use custom built clang, so I’d not recommend you to use this clang for building apps for production usage. Apple provides patched version, and we can’t know the difference between them. Also, it needs a lot of efforts to make it work, which doesn’t make it widely usable. Another issue you might face is unstable API, cause it uses internal API which changes continuously.You still can use it on your system for different diagnostic purposes, but please do not force other people to depend on such heavyweight things.If you have any comments, questions or suggestions feel free to ask me on twitter, open issue on GitHub, or just leave a comment here.Happy hacking!