User's Guide

Consider the following C source file hello.c:

static const char hello[] = "Hello, World!";

We retrieve the string constant using a Lua script hello.lua:

local gcc = require("gcc")

-- send assembler output to /dev/null

-- invoke Lua function after translation unit has been parsed
gcc.register_callback(gcc.PLUGIN_FINISH_UNIT, function()
  -- get global variables in reverse order of declaration
  local vars = gcc.get_variables()
  for i = #vars, 1, -1 do
    -- initial value is a string constant

The plugin is loaded into GCC by passing its path to -fplugin:

gcc -S hello.c -fplugin=./gcc/ -fplugin-arg-gcclua-script=hello.lua

For detailed examples, please refer to the source code of the test suite.


The Plugins section of the GCC Internals explains writing, building and loading plugins. The GENERIC section describes the format of abstract syntax trees. Relevant GCC source files are gcc/tree.h, gcc/tree.def and gcc/tree-dump.c for the GENERIC format, and gcc/cgraph.h for entry points to global variable, function and type declarations.

The GCC Wiki links to documentation and existing plugins.

Boris Kolpackov has written a three-part series on Parsing C++ with GCC plugins.