Building GCC Plugins – Part 1: C++ 11 Generalized Attributes

Historically with C and C++ compilers, you get what you get and you don’t get upset.  There was little or no facility for extending the compiler or for the kind of meta-programming models available in other languages.  Macro or template meta-programming and source code generation has been an option for many, many years but annotation based meta-programming which is a prominent feature of many popular Java frameworks has been very difficult to replicate in C++.

Starting with version 4.5.0, the GCC compiler supports ‘plugins’ which are dynamically loaded modules which make it possible for developers to enrich the compiler without having to modify the GCC source code itself.  There is a bit of information on the GCC Wiki and an excellent set of articles by Boris Kolpackov on the basics of writing GCC plugins.  Beyond those references, I found little else.  I spent a lot of time digging through GCC header files and using trial-and-error to work through decoding the GCC internal data structures.

Starting with GCC version 4.8.0, the compiler supports the C++ 11 standard for ‘generalized attributes’.  GCC (and many other C/C++ compilers) have had attributes for quite some time, but C++ 11 now specifies a standard syntax for both attributes and attribute namespaces.

Taken together, plugins and C++ 11 generalized attributes provide a framework within which annotation based meta-programming may be approached in the GCC compiler.  To be clear, it is not necessarily easy to do – there is a long learning curve for GCC internals – but at least it is achievable without requiring pragmas, code generators or direct modification of the GCC compiler itself.

In this and a series of followup posts, I’ll walk through creating a GCC plugin, adding custom attributes, decoding and traversing the Abstract Syntax Tree (AST) and simple modifications to the AST.

C++11 Generalized Attributes

The GCC compiler has had attributes for quite some time, primarily to provide hints to the compiler or for injecting debugging code.  The GCC syntax appears below:

__attribute__ ((aligned (16)))

Contrast the above with the equivalent C++ 11 syntax:

[[gnu::aligned (16)]]

In the C++ specification, the __attribute__ keyword is gone and double brackets are used to surround the attribute.  Also, the new specification introduces namespaces for attributes.  In the above example, the ‘gnu’ namespace is implicit in the GCC style attribute but must be called out explicitly when using the C++ standard syntax.

Development Environment

In general, I start by creating a VM for the project I will be working on – essentially one VM per project.  In a series of prior posts I walk through creating an Ubuntu development VM, the process required to build a debug version of GCC and how to debug GCC in the Eclipse CDT IDE.  The rest of this post assumes that base environment but there is no reason why the process presented herein could not be modified for a different but functionally similar environment.

For generalized attributes, you will need GCC version 4.8.0 or later.

Creating a GCC Plugin

Step 1: Create a pair of C++ Projects in Eclipse CDT

Perhaps the most straightforward way to build and debug a plugin in Eclipse is to create one  C++ project for the plugin itself and a second ‘dummy’ C++ project which is used to hold the source files to be compiled by a debug instance of GCC with the plugin loaded.  Figure 1 shows the Eclipse Project Explorer window for this simple project.  The ‘GCCAttributesAndPlugin’ project should be an empty shared object and a ‘HelloWorld’ executable is fine for the ‘TestProject’.

Two C++ Projects

Figure 1: Two C++ Projects in Eclipse Explorer

Step 2: Modify the Compiler Settings for the Plugin Project

A small number of modifications to the plugin project C++ compiler settings are necessary to insure the correct version of the compiler is used and the plugin header files are found.  Figure 2 contains an image of the Eclipse C++ Settings dialog with the ‘Command’ changed to point to the 4.8.0 version of the g++ compiler built previously.  Other changes are found in the ‘All Options’ but those will actually be introduced in the next steps.

Figure 2: C++ Compiler Settings

Figure 2: C++ Compiler Settings

Next, the include path for the GCC plugin header files needs to be added to the project.  For an environment configured per my prior post, the correct path is: ‘/usr/gcc-4.8.0/lib/gcc/x86_64-linux-gnu/4.8.0/plugin/include’ and can be seen in the C++ Settings Includes Dialog in Figure 3.

Figure 3: C++ Settings Include Dialog

Figure 3: C++ Settings Include Dialog

Next, a couple of options need top be added to the Miscellaneous dialog as shown in Figure 4.  The two that will need to be added to a vanilla project are: ‘-std=c++0x’ to indicate the C++ 11 language specification should be used and ‘-gdwarf-3’ to force the compiler to emit debugging symbols in dwarf-3 format, as the latest version of the gdb debugger will not accept the default compiler dwarf formation.

Figure 4: C++ Settings Miscellaneous

Figure 4: C++ Settings Miscellaneous

Finally, just as the ‘Command’ was changed for the C++ compiler, the same needs to be done for the Linker as shown in Figure 5.

Figure 5: Linker Settings Dialog

Figure 5: Linker Settings Dialog

Step 3: Modify the Discovery Options for the Plugin Project

To insure that the Eclipse IDE finds the correct include path paths and indexes the project properly, the ‘Discovery Options’ need to be changed to reflect the compiler being used for the project itself.  Figure 6 shows the modification to the ‘Compiler Invocation Command’ for the discovery function.

Figure 6: Discovery Options Dialog

Figure 6: Discovery Options Dialog

Step 4: Source Code for the Plugin

Little source code is required to register custom attributes and build a plugin.  The code for a very simple plugin with attributes appears below.

 * gccplugin.cpp
 * Created on: May 17, 2013
 * Author: steve
#include <iostream>
#include "config.h"
#include "gcc-plugin.h"
#include "tree.h"
#include "cp/cp-tree.h"
#include "diagnostic.h"
#include "plugin.h"

// The following global int is needed to let the compiler know that this plugin is//     GPL licensed

int plugin_is_GPL_compatible;

static tree HandleAttribute( tree* node,
                             tree attrName,
                             tree attrArguments,
                             int flags,
                             bool* no_add_attrs )
    std::cerr << "Encountered Attribute: " << IDENTIFIER_POINTER( attrName );

    // Print the arguments

    std::string separator = " ";
    for( tree& itrArgument = attrArguments; itrArgument != NULL_TREE; itrArgument = TREE_CHAIN( itrArgument ) )
        std::cerr << separator << TREE_STRING_POINTER( TREE_VALUE ( itrArgument ));
        separator = ", ";

    std::cerr << std::endl;

    // Just return a null tree now.

    return( NULL_TREE );

static struct attribute_spec g_GeneralizedAttribute1 =
 "generalized_attribute_1", 0, -1, false, true, false, HandleAttribute, false

static struct attribute_spec g_GeneralizedAttribute2 =
 "generalized_attribute_2", 0, -1, false, false, false, HandleAttribute, false

//    The array of attribute specs passed to register_scoped_attributes must be NULL terminated
attribute_spec demoScopedAttributes[] = { g_GeneralizedAttribute1, g_GeneralizedAttribute2, NULL };

static void RegisterAttributes( void* eventData,
                                void* userData )
 register_scoped_attributes( demoScopedAttributes, "demo" );

static void GateCallback( void* eventData, void* userData )
     // If there has been an error, fall through and let the compiler handle it
    if( errorcount || sorrycount )
    std::cerr << "IPA Passes Starting for File: " << main_input_filename << std::endl;

int plugin_init( plugin_name_args*   info,
                 plugin_gcc_version* ver )
    std::cerr << "Starting Plugin: "<< info->base_name << std::endl;
    register_callback( info->base_name, PLUGIN_ATTRIBUTES, &RegisterAttributes, NULL );
    register_callback( info->base_name, PLUGIN_ALL_IPA_PASSES_START, &GateCallback, NULL );
    std::cerr << "Plugin Initialized, attribute registered" << std::endl;
    return( 0 );

The set of includes are pretty much the bare minimum needed for a plugin.  The ‘config.h’ file is the compiler configuration which is generated during the build process and can be found with the compiler includes.  Aside from the inclusion of ‘<iostream>’ to provide output to the console, the remaining includes are for plugin and attribute support.  Since GCC 4.8.0 is compiled using the g++ compiler, it is no longer necessary to wrap the plugin includes with ‘extern C{}’ to denote the difference in name mangling.  Also of note is the global symbol ‘plugin_is_GPL_compatible’ which the compiler checks for in the plugin library when it loads the plugin.  If the compiler does not find this global symbol, it will not finish loading the plugin.

The ‘HandleAttribute()’ function is a callback that is invoked by the compiler when it encounters a custom attribute registered by the plugin.  A separate function pointer to a callback is associated with each attribute registered, so it would be completely reasonable to have a separate callback for each custom attribute.  Within the handler, all we do is print out the attribute name and the attribute arguments.  The arguments are a GCC tree list of constant values – more on how to interpret GCC trees will appear in followup posts.

Next are static specifications of the two custom attributes.  This structure is defined in ‘tree.h’ which also contains good descriptions of the meanings of the fields.  I will not re-iterate that documentation here, but be sure to read through the definition to insure you are  passing the right values.  The ‘RegisterAttributes()’ callback function appears next.  The namespace for scoped attributes appears as the second argument to the ‘register_scoped_attributes()’ – for this case the namespace is ‘demo’.

The ‘GateCallback()’ function is invoked by the plugin framework in response to registrations for notification when specific passes have been completed by the compiler.

Finally, the ‘plugin_init()’ function is the entry point for the plugin.  After the compiler loads the plugin shared object then it will call this function.  There is an argument block and a version information block passed to the function, neither of those arguments are used in this simple example.  This function registers two callbacks: the first to register the custom attributes and the second to register a gate callback on the PLUGIN_ALL_IPA_PASSES_START event.  Once again, for further detail on the parameters for the ‘plugin_init()’ function, the best bet is to refer to the inline documentation in the GCC source code.

Step 5: Source Code for the Test Project

The source code for a test project with a pair of classes with attributes appears below.  This file is just the auto-generated ‘HelloWorld’ project source code with the two demo classes added.  Note the C++ 11 syntax for the attributes with the ‘demo’ namespace.

// Name : TestProject.cpp
// Author :
// Version :
// Copyright : Your copyright notice
// Description : Hello World in C++, Ansi-style

#include <iostream>
using namespace std;

class [[demo::generalized_attribute_1( "arg1", "arg2" )]] ClassWithAttribute1

class [[demo::generalized_attribute_2( "arg3" )]] ClassWithAttribute2

int main() {
 cout << "!!!Hello World!!!" << endl; // prints !!!Hello World!!!
 return 0;

Step 6: Create the .gdbinit file

The ‘.gdbinit’ file contains configuration information for the GDB debugger when it is invoked by the Eclipse IDE.  For debugging a GCC plugin, the file should have at least the following contents:

set schedule-multiple
dir ~/gcc_build/4.8.0/build/gcc
dir ~/gcc_build/4.8.0/gcc
dir ~/gcc_build/4.8.0/gcc/cp
dir ~/gcc_build/4.8.0/gcc/lto
source ~/gcc_build/4.8.0/build/gcc/

The ‘.gdbinit’ file may be placed in the root directory of the plugin project.

Step 7: Create a Debugger Profile for the Plugin Project

To debug the plugin inside of Eclipse, the approach I use is to adjust the debugging launch profile for the plugin project so that it launches GCC and loads the plugin to compile the source code in the ‘Test Project’.  The first step is to set the ‘C/C++ Application’ to the compiler itself in the ‘Main’ dialog of the Debug Launch Configuration Properties, as shown in Figure 7.

Figure 7: Debug Profile Main Dialog

Figure 7: Debug Profile Main Dialog

The next step is to tell the compiler to load the plugin, specify C++ 11 semantics and point the compiler at the source code file in ‘TestProject’, as shown in Figure 8.

Figure 8: Arguments Tab for the Debug Launch Profile

Figure 8: Arguments Tab for the Debug Launch Profile

Next, the LD_LIBRARY_PATH and the PATH environment variables need to be enriched to add the paths to the GCC 4.8.0 compiler executables and libraries.  This is done on the ‘Environment’ tab as shown in Figure 9.  Additional detail is shown in Figures 10 and 11.

Figure 9: Debug Profile Environment Tab

Figure 9: Debug Profile Environment Tab

Figure 10: LD_LIBRARY_PATH setting

Figure 10: LD_LIBRARY_PATH setting

Figure 11: PATH environment variable setting

Figure 11: PATH environment variable setting

Finally, on the ‘Debugger’ tab, insure that the ‘GDB Command Line’ points to your ‘.gdbinit’ file created above and check the ‘Automatically debug forked process’ box.  GCC forks the g++ compiler from a main controller process, so if this checkbox is blank, then GDB will not debug the forked g++ process where the plugin actually gets loaded.

Figure 12: Debug Profile Debugger Tab

Figure 12: Debug Profile Debugger Tab

Step 8: Pass arguments to the plugin

 The command line syntax to pass one or more arguments to a plugin is a little tricky.  Given that a multiplicity of plugins may be simultaneously loaded into GCC, the disambiguation of which arguments are associated with which plugin are embedded in the command line.  The syntax to pass an argument to a plugin is:

-fplugin-arg-'plugin name'-'argument name'='argument value'

For this example, the program arguments tab would contain the following:

Figure 9 : Debug Arguments Tab with Plugin Arguments

Figure 13: Debug Arguments Tab with Plugin Arguments

Upon entering plugin_init(), the info->argc argument will contain the count of plugin arguments and the info->argv->key and info->argv->value arrays will contain the key value pairs passed on the command line.

Not that the attached example code does not include plugin arguments.

Step 9: Run the code

If you run the debug profile just created for the plugin project you should see output like this in the console:

Figure 13: Debug Console Output

Figure 14: Debug Console Output

That should do it, you have a basic GCC plugin and attribute framework in place.

Prepackaged Projects

If you have a development environment build as described in my prior posts, then you should be able to take the contents of the attached zip file and simply extract them into your workspace to get the two projects.  Also in the zip file is the debug profile which is in the ‘.launches’ directory.  This directory needs to be placed under the ‘.metadata/.plugins/org.eclipse.debug.core’ directory for Eclipse to recognize the profile.  If you drop in the directory while Eclipse is running, then you will need to re-start Eclipse.

Project Files

Creating an OpenStack Keystone ‘HelloWorld’ Extension

The OpenStack ‘cloud operating system’ provides a model, framework and  a core set of platform services managing core virtualized datacenter resources.  As of the Folsom release, the following services are packaged as part of the solution:

  • Keystone – Identity, Authentication and Authorization
  • Glance – Image Management
  • Nova – Compute
  • Quantum – Network
  • Swift – Object Storage
  • Cinder – Block Storage
  • Horizon – Web App Dashboard

Development of OpenStack is a collaborative venture between a global community of individuals and organizations.  Given the loosely coupled, standards based approach to development, a systems architecture composed of loosely coupled services adhering to a standardized API specification was needed to permit the project to move forward rapidly with a minimum of centralized coordination.

One of the core elements of the OpenStack architecture is support for extensibility.  The evolution of OpenStack will in part be governed by the development of experimental extensions to the base platform which may be promoted to first-class members of the platform should the extension prove generally valuable.  Beyond that, extensibility is needed to permit ‘customization’ of a base OpenStack package for specific deployment configurations or service requirements.

Though the Extension API has some sparse documentation on the site, there don’t yet appear to be any simple ‘Hello World’ type examples for adding an extension to the Keystone service.  The process is not difficult but it took me some poking around in the code to figure out how to add one of my own.

Development Environment :

I use the DevStack distribution installed on an Ubuntu 12.04 Server OS for development.  In the absence of intrusive network proxies or firewalls, the DevStack distribution ‘just works’.  That said, DevStack is neither intended nor suitable for production deployments.  Be sure to read the DevStack caveats before you start using it so that you minimize potentially unpleasant surprises

Creating an Extension :

Step 1: Create subdirectory under ‘contrib’

For a vanilla DevStack installation, the solution root directory is ‘/opt/stack’.  Keystone extensions are typically placed in individual subdirectories of ‘/opt/stack/keystone/keystone/contrib’.  For this example create a directory named ‘hello_world’.

Step 2: Create a file for the extension mapper and controller

The OpenStack extension architecture relies on the wsgi python framework.  There are some OpenStack wrapper classes that simplify creating an extension.  The code should be placed in the ‘contrib’ directory.  The python code for the hello_world extension appears below.

# vim: tabstop=4 shiftwidth=4 softtabstop=4

# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.

from keystone.common import wsgi

from keystone import identity
from keystone import token

class HelloWorldExtension(wsgi.ExtensionRouter):

    def add_routes(self, mapper):
        controller = HelloWorldController()

        mapper.connect( '/example/hello_world',

        mapper.connect( '/example/hello_world/{identifier}',

class HelloWorldController(wsgi.Application):

    def __init__(self):
        self.token_api = token.Manager()
        super(HelloWorldController, self).__init__()

    def get_hello_world(self, context):
#       self.assert_admin(context)
        return {
            'SEF-EXAMPLE:hello_world': [
                    'hello': 'world',
                    'description': 'Simple Hello World Keystone Extension',

    def get_hello_world_with_id(self, context, identifier):
#       self.assert_admin(context)
        return {
            'SEF-EXAMPLE:hello_world_id': [
                    'hello': 'world',
                    'description': 'Simple Hello World Keystone Extension with Identifier',
                    'identifier': identifier,

The code is fairly straightforward.  The HelloWorldExtension class creates a controller an in the add_routes() method it associates URLs with code handlers.  The code handlers are defined in the HelloWorldController class.

There are two elements of the controller that merit a bit of explanation.  First, the example contains the commented out command: ‘self.assert_admin(context)’ in both code handlers. This command enforces authentication for the extension. It is commented out in the example to make the example easier to invoke with curl. Second, in the mapper the connection: “mapper.connect( ‘/example/hello_world/{identifier}'” specifies ‘{identifier}’ as an argument to the handler. The handler signature: ‘def get_hello_world_with_id(self, context, identifier)’ includes ‘identifier’ as the parameter parsed from the URL.

There are formalized naming conventions for extensions and their namespaces described in the OpenStack documentation.  For anything more than a HelloWorld example, these conventions should be followed.

Step 3: Create to load the extension

The ‘’ file below should be placed in the  ‘contrib’ subdirectory with the extension code. The file is very straightforward, it just loads the extension.

# vim: tabstop=4 shiftwidth=4 softtabstop=4
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.

from keystone.contrib.hello_world.core import *

Step 4: Add an entry for the extension filter in keystone.conf

With the extension created and the ‘’ file to load it, the next step is to modify the keystone configuration file to add a filter entry for the extension and then add the filter to the admin API pipeline.  For a standard OpenStack install, this would be the ‘/etc/keystone/keystone.conf’ file.  For DevStack, modifications should be made to the ‘/opt/stack/keystone/etc/keystone.conf.sample’ file which serves as a template for the ‘keystone.conf’ file generated during DevStack start-up.  The content to be added to the configuration file appears below:

paste.filter_factory = keystone.contrib.hello_world:HelloWorldExtension.factory

pipeline = access_log sizelimit stats_monitoring url_normalize token_auth admin_token_auth xml_body json_body debug stats_reporting ec2_extension s3_extension crud_extension hello_world_extension admin_service

The ‘[filter:hello_world_extension]’ should be added to the end of the list of filters in the configuration file.  The ‘[pipeline:admin_api]’ should already exist in the file, so all that is necessary for that line should be to add the name of the filter to the pipeline.

Step 5: Add self.extensions entry to

Extensions are not self-describing so when querying an OpenStack Keystone instance for the extensions it has loaded, it is necessary to add the descriptive metadata to the ‘’ class.  For DevStack, this file can be found at ‘/opt/stack/keystone/keystone/’.  The code fragment below should be inserted in to the ‘__init__()’ method.

self.extensions['SEF-HELLO-WORLD'] = {
 'name': 'Hello World Example Extension',
 'namespace': ''
 'alias': 'SEF-HELLO-WORLD',
 'updated': '2013-03-18T13:25:27-06:00',
 'description': 'Openstack extensions to Keystone v2.0 API '
 'enabling Admin Operations.',
 'links': [
             'rel': 'describedby',
             'type': 'text/html',
             'href': '',

Step 6: Check Extension Functionality

If you are using DevStack, the easiest thing to do is to restart it and it will compile and load the new extension. After it has started, there should be two new files: ‘core.pyc’ and ‘__init__.pyc’ in the ‘contrib/hello_world/’ subdirectory. Files with ‘.pyc’ extensions are ‘compiled python’ files which contains python byte code. To check the new extension description, use the following ‘curl’ command and you should see the description in the response:

$ curl http://<em>openstack_ip_addr</em>:35357/v2.0/extensions

{"extensions": {"values": [{"updated": "2013-03-18T13:25:27-06:00", "name": "Hello World Example Extension", "links": [{"href": "", "type": "text/html", "rel": "describedby"}], "namespace": "", "alias": "SEF-HELLO-WORLD", "description": "Openstack extensions to Keystone v2.0 API enabling Admin Operations."}}

To actually invoke the extension, use the following for the two non-authenticated operations:

$ curl http://<em>openstack_ip_addr</em>:35357/v2.0/example/hello_world

{"SEF-EXAMPLE:hello_world": [{"hello": "world", "description": "Simple Hello World Keystone Extension"}]}

$ curl http://<em>openstack_ip_addr</em>:35357/v2.0/example/hello_world/token

{"SEF-EXAMPLE:hello_world_id": [{"identifier": "token", "hello": "world", "description": "Simple Hello World Keystone Extension with Identifier"}]}

Note in the second example that the URL parameter ‘token’ has been passed to the extension handler as the ‘{identifier}’.


The above gets you going with a Keystone extension, at least for Folsom.  Given the rate at which OpenStack is evolving, it is quite possible that the extension framework may well change in an upcoming release.  One nice enhancement would be to make extensions self-describing which would eliminate the need to add that descriptive meta-data to the ‘’ file.

Debugging GCC in Eclipse CDT 4.2

My favored C++ development environment on Linux is Eclipse CDT.  There are a number of different IDEs available for Linux but I use the Eclipse IDE for Java development and find it easier to stick to that tool for C++.  Eclipse 4.2 CDT is mature and many of the rough edges found in prior releases have been filed off in Juno.

As I am working on a GCC plugin, I needed to create a debug build of GCC and then figure out how to debug it in the IDE.  The procedure to build a debug version of GCC 4.7.2 in Ubuntu 12.04 can be found in my post here.  Once you have a debug GCC built, adding Eclipse CDT and configuring a project for GCC debugging is a straightforward process – but there are a few details that can be added to the environment that make GCC development in Eclipse much more tractable.

Step 1:  Install Java 1.7

Eclipse is supported with the Oracle, IBM and OpenJDK packages.  In the past I’ve typically relied on the Sun JDKs and feel most comfortable using those JDKs for Eclipse.  I use the Web Upd8 PPA repository for Ubuntu to install the JDK.

$ sudo add-apt-repository -y ppa:webupd8team/java
$ sudo apt-get update
$ sudo apt-get install -y oracle-jdk7-installer
$ sudo update-java-alternatives -s java-7-oracle

You can check that the JDK installed correctly by asking for the java version

$ java -version

Step 2: Install Eclipse 4.2

Eclipse 4.2 is not yet in the official Ubuntu repository, so it must be installed manually.  I haven’t been able to find a way to use wget to pull the Eclipse archive directly, so I use the version of Firefox bundled with Ubuntu 12.04 to download the archive.  The Eclipse archives can be found at:  For Eclipse 4.2 CDT you want to download: eclipse-cpp-juno-linux-gtk-x86_64.tar.gz, assuming you are using 64 bit Ubuntu.

$ mkdir ~/eclipse
$ cd ~/eclipse
$ mkdir 4.2
$ cd 4.2

# Download Eclipse 4.2 from:
# The archive you want should be: eclipse-cpp-juno-linux-gtk-x86_64.tar.gz

$ tar -xzvf eclipse-cpp-juno-linux-gtk-x86_64.tar.gz
$ sudo cp -r eclipse /usr/lib/
$ sudo cp eclipse/icon.xpm /usr/share/pixmaps/eclipse.xpm

If this is a first install of Eclipse, you will probably want to create a script in /usr/bin that simply launches Eclipse from /usr/lib/eclipse.

$ sudo sh -c "echo '/usr/lib/eclipse/eclipse' >> /usr/bin/eclipse"
$ sudo chmod +x /usr/bin/eclipse

If you want to create a menu entry for the IDE, the best bet is to use the menu management tool: Applications > System Tools > Preferences > Main Menu.  It should automatically pick up the icon from the pixmaps directory.

Step 3: Create two Simple C++ Projects to Debug GCC

From here on, the example assumes that GCC was built with –prefix=/usr/gcc-4.7.2 and –program-suffix=-4.7.2.  If your debug version of GCC was built with different values, then substitute accordingly.

Inside Eclipse, create two new ‘Hello World’ C++ Projects.  Use the ‘Executable’ project – not a ‘GNU Autotools’ project.  For this example I labelled the first project ‘GCC Debug Test’ and the second ‘Project To Build’.  ‘GCC Debug Test’ will be configured to build ‘Project to Build’ using the debug version of GCC.  For clarity, ‘GCC Debug Test’ isn’t even built, it is needed to configure the debug settings for GCC.

First, create a custom .gdbinit file in the ‘GCC Debug Test’ working directory.  Do this by copying the .gdbinit file from the gcc build directory into the project working directory and then fixup the paths in the file to point back to the build directory. The .gdbinit file created during the gcc build process provides a collection of scripts that can be used to print gcc data structures while debugging – this will prove invaluable.   FInally, add ‘set schedule-multiple’ as the first line of the  file – this option causes gdb to track multiple processes in a single debugging session.  The .gdbinit file should look something like this:

set schedule-multiple

dir ~/gcc_build/4.7.2/build/gcc
dir ~/gcc_build/4.7.2/gcc
dir ~/gcc_build/4.7.2/gcc/cp
dir ~/gcc_build/4.7.2/gcc/lto
source ~/gcc_build/4.7.2/build/gcc/

In the ‘GCC Debug Test’ project, go to the ‘Run > Debug Configurations’ dialog and create a new ‘C/C++ Application’ debug configuration.  On the ‘Main’ tab, enter the path to the ‘gcc-4.7’ debug executable in the ‘/usr/gcc-4.7.2/bin’ directory in the ‘C/C++ Application:’ field in the dialog and click ‘Apply’.

After completing the ‘Main’ tab dialog, click on the ‘Arguments’ tab and enter the path to the test file to be compiled and click ‘Apply’.

Next, click on the ‘Environment’ tab and create two variables: LD_LIBRARY_PATH and PATH.  For LD_LIBRARY_PATH, add the paths to the ‘lib’, ‘lib64’ and ‘lib64/debug’ directories for the GCC build to the front of the environment variable.  For PATH, add the path to the ‘bin’ directory to the front of the path as well.  For both environment variables, add the original paths to the end of the variable.  Make sure the ‘Replace native environment with specified environment’ radio button is selected.

Finally, click on the ‘Debugger’ tab.  In that dialog, insure the ‘Stop on startup at: main’ checkbox is checked.  Enter the path to the .gdbinit file created above into the ‘GDB command file’field.  Finally, check the ‘Automatically debug forked processes’ checkbox.  Since the gcc-4.7.2 application is just a driver for the actual compiler, unless this field is selected the debugger will not debug into the actual compiler when that process is forked by gcc.  Click ‘Apply’ and the configuration is complete.


With the debug configuration finished, click ‘Debug’ and gdb should launch and stop at the ‘main’ function for gcc-4.7.

Step 4 : Making Debug GCC the version of GCC to use for Builds

This step is not *strictly* necessary, though building a plugin or modifying the gcc suite and compiling those modifications with a different version of gcc is ill advised for all sorts of good reasons.  Changing compilers in GCC is straightforward, though a multi-step process.

First, navigate to the Project->Properties->Settings dialog and select ‘GCC C++ Compiler’.  Set the ‘Command’ field to the debug version of g++.  I also set the CXX0X experimental symbol and the -std=c++0x option.

Set the ‘Command’ field for the ‘GCC C++ Linker’ as well.

After pressing ‘OK’, the newly built compiler will not be used by Eclipse for compiling this project.  There doesn’t appear to be a way to set these options globally, so the same changes will have to be made for each project you wish to compile with the the debug GCC suite.

Build a Debug Version of GCC 4.7.2 or 4.8.0 for Ubuntu 12.04


This procedure is predicated on using Ubuntu 12.04 LTS amd64 as the development OS and GCC version 4.6.3 packaged in that version of Ubuntu to bootstrap the GCC build itself.  A key complication for the build process is that the multiarch changes being made to GCC to support improved cross-compilation functionality are not yet supported by out-of-the-box Debian based Linux distributions, like Ubuntu.  The following link contains the details and the extra symbolic links needed to get the build to complete.

I have tried to build GCC 4.6.3 on Ubuntu 12.04 i386 (i.e. 32 bit) but with marginal success.  The build process required a bit more patching than I normally like.  With Ubuntu 12.04 64 bit, one set of initial modifications was all I needed to get the build to run from start to finish without intervention.

Step 1: Prepare VM (Optional)

I strongly suggest using a purpose-built VM for GCC development.  Since GCC forms the foundation of a development environment, mixing GCC compiler development with development of other software elements could be ill advised.  As described below, GCC doesn’t build seamlessly on  Ubuntu, so isolating your GCC development system with the extra symbolic links added to build GCC will eliminate the risk of those changes to the environment affecting other projects sharing the same environment.  Additionally, GCC has a very configurable build system and you may well end up experimenting with configurations that might not play well with other software you are building.

See: Building an Ubuntu 12.04 VM for Development for my short post on creating a development VM using ESXi.

Step 2: Install Required Build Support and Source Code Packages

If you wish to build GCC 4.8.0, read over the modifications section at the end of this post for the tweaks to this process for 4.8.0.

As my goal is to build a debug version of GCC for plugin development, I have no desire to build some of the dependencies from source.  If you want to build debug versions of the libraries gcc depends upon, then follow the process outlined here.  The information provided by Solarian Programmer on that link was quite helpful to me as I plowed through the build process.  The most straightforward way to insure your environment has the right dependencies in place for the build is to get the ‘build-dep’ package for the GCC 4.7 series.  Once the dependencies are in place, I pull the archive containing the GCC source and put it into a separate build directory in my home folder.  Mirrors for GCC source may be found here:, choose one appropriate for your geography.

The script below captures my sequence of commands:

$ sudo apt-get build-dep gcc-4.7-base
$ mkdir gcc-build
$ cd gcc-build
$ mkdir 4.7.2
$ cd 4.7.2
$ wget 'your mirror here'/gcc-4.7.2.tar.bz2
$ tar -jxvf gcc-4.7.2.tar.bz2

Step 3 : Patch the OS for the Build :

Patching the OS for the GCC build requires defining a pair of symbolic links to insure the build system can find the right include files and libraries for the build:

$ cd /usr/include
$ ln -s x86_64-linux-gnu/* .
$ cd /usr/lib
$ sudo ln -s x86_64-linux-gnu/crt* .

You will get some ‘failed to create symbolic link’ messages when creating links in the include directory, these don’t appear to cause problems.  I used elevated permissions to insure all the links in /usr/lib directory were created.

Step 4 : Configure and Build GCC

I typically create a build directory inside of the GCC version specific directory and build in it.  This keeps all the source code and executables together in one directory structure and makes it easy to remove broken builds by simply removing the entire directory.  There are a fair number of configuration options for the build; I run ‘gcc -v’ to get the configuration of the stock build for the platform and then pick the options that seem to make sense.  For this build, be sure to add the –disable-multilib option to prevent the build system from trying to build the multi-arch versions of gcc.  If you are interested in building gcc plugins, then also include the –enable-plugin configuration option.

If you plan on installing this debug build into an environment which already has a version of GCC installed, then you ought to use the –prefix and –program-suffix configuration options to distinguish your build from the stock build.  Ubuntu 12.04 includes GCC 4.6.3 and it is not generally a good idea to replace the version of GCC that ships with an OS image; parts of the system may depend on that version of the compiler suite.  The –prefix configuration option specifies the directory into which the newly built gcc suite should be installed.  The –program-suffix option allows you to specify a label to be appended to all the executable files generated in the build.  For example –program-suffix=-4.7.2 would result in the gcc executable being labelled ‘gcc-4.7.2’.

For make, the ‘-g3’ flag causes the compiler to emit the maximum level of debug information, including debugging of macros in gdb.  The ‘-O0’ option turns off optimizations, as some optimizations result in changes to the AST tree that don’t map well to the source code for debugging.  The ‘-j4’ option allows make to fork up to 4 child processes to parallelize the build.  Stage1 builds the C compiler with the compiler packaged with the Ubuntu distribution, 4.6.3 in my case.  Once the C compiler has been built, the rest of the gcc suite will be built with that compiler.

$ cd ~/gcc-build/4.7.2/gcc-4.7.2
$ mkdir build
$ cd build
$ ../configure --build=x86_64-linux-gnu --disable-multilib --prefix=/usr/gcc-4.7.2 --program-suffix=-4.7.2 --with-system-zlib --without-included-gettext --enable-threads=posix --enable-libstdcxx-debug --enable-libstdcxx-time=yes --enable-plugin --disable-werror --with-arch-32=i686
$ make -j4 STAGE1_CFLAGS="-g3 -O0" all-stage1
$ make -j4 CXXFLAGS="-g3 -O0"

After issuing the last make command, you will have plenty of time to get a refreshing beverage while the build system churns away.  When the build completes, you should have a complete gcc compiler suite built for debugging.

Step 5 : Install GCC

With the suite built, you have the choice of leaving the build directory alone and specifying the appropriate paths to the compiler, includes and libraries in the build tree or you can install the compiler into appropriate system directories.  In the absence of specifying –prefix, the suite will install into /usr/local.  If you have specified –prefix, then the suite will install into a tree rooted in the specified directory.  For the example above, the suite would install below /user/gcc-4.7.2.  The suite may be installed wit the following command.

$ sudo make install

The sudo command is needed if you will be installing into a system directory.

Modifications for GCC 4.8.0:

This approach works as-is for gcc 4.8.0; needless to say you must substitute ‘4.8.0’ for ‘4.7.2’ throughout the process.  There is not yet a ‘build-dep’ package for ‘gcc-4.8-base’ but I found that using the package for ‘gcc-4.7-base’ works.

One issue you will encounter when using GCC 4.8.0 on an otherwise stock Ubuntu 12.04 is that GCC 4.8.0 now defaults to the DWARF-4 format for debugging info whereas the current version of gdb packaged with Ubuntu 12.04 (gdb version 7.4) expects DWARF-3 debugging information.  You have two choices: 1) you can upgrade to gdb 7.5 or above as DWARF-4 is the default format for 7.5 and beyond or 2) add the compiler setting: ‘-gdwarf-3’ to your projects to force the compiler to emit DWARF-3 debugging information.

I found GCC 4.8.0 to work every bit as well as GCC 4.7.2 and 4.8.0 has a couple of nice C++ 11 enhancements, generalized attributes for example.

Building an Ubuntu 12.04 VM for Development

I use the ESXi hypervisor, I find it ‘just works’ and the VSphere client is easy to use.  That said, as the bulk of virtualization is moving into the CPU silicon there is increasing parity amongst the mainstream hypervisors.  There is no reason why Xen, KVM, Hyper-V or VirtualBox won’t work equally well.

For Ubuntu 12.04 on ESXi, I take the defaults presented for a ‘typical’ Ubuntu 64Bit VM.  I allocate 48GB of thin-provisioned storage and 2GB of memory.  For this example I used the 12.04.1 64Bit Desktop Ubuntu Desktop build:

Ubuntu 12.04.1 Desktop 64 Bit

I prefer the Gnome Classic desktop and I install it immediately after the obligatory update and upgrade.

sudo apt-get update
sudo apt-get upgrade
sudo apt-get install gnome-shell

Reboot after the update and gnome-shell install.  When the login screen reappears, click on the Ubuntu icon to the right of the user name.  A dropdown menu will appear with a number of desktop selections, I choose ‘GNOME Classic’.

For remoting the Ubunutu GUI, I find FreeNX provides the easiest to use, most responsive platform.  The install and configuration of that package may be found here: and the condensed procedure for 12.04 follows:

sudo add-apt-repository ppa:freenx-team
sudo apt-get update
sudo apt-get install freenx
cd /usr/lib/nx
sudo wget
sudo tar xvf nxsetup.tar.gz
sudo ./nxsetup --install --setup-nomachine-key
cd ~

I use the NX Client for Windows to connect to the development server.  The client may be found here:

For ESXi, I also install open-vm-tools, it is easier than adding the VMWare repositories or installing the tools from the server itself (which bypasses the package systems as well).

sudo apt-get install open-vm-tools

After all of the above is complete, I typically export the VM as an OVF so I can quickly rebuiild the OS if I damage the one I am working with or create new VMs without the handiwork.