Getting to know the CDT Autotools Plug-in

The Autotools plug-in is a Red Hat initiative to allow existing open source C/C++ projects to be maintained using the Eclipse CDT (C/C++ Development Tooling). The plug-in is previewed in the Red Hat Developer Suite (RHDS) 3 product. It extends the Eclipse CDT and adds features needed by C/C++ projects that use Autotools and have a configuration step.

Such projects perform tests at configuration time that ultimately determine how to construct the Makefile(s). For example, configuration might search for a C compiler on the system and verify that the compiler can successfully build an executable for the target. Optional features might be included/excluded via configuration. Without the Autotools plug-in, significant manual intervention is required to build such a project using the current CDT.

This article reviews various features of the plug-in and how they are used. Some familiarity with the CDT is assumed. Dynamic examples are provided that show how to perform various tasks.

To begin, check out a known Autotools project that is reasonably complex. For example, the newlib C library can be checked out from CVS as follows (using anoncvs for the password):

cvs -z 9 -d :pserver:sources.redhat.com:/cvs/src login
cvs -z 9 -d :pserver:sources.redhat.com:/cvs/src co newlib

Newlib is an embedded-platform C library that can be configured to run on many platforms. This examples builds it natively on an i686 Linux platform under Eclipse. Therefore, only a native toolset needs to be installed: gcc, ld, binutils, gnu make, and so forth.

After checking out newlib, designate it as an Autotools project. This enables the extended functionality in the Autotools plug-in.

As seen in Figure 1, configuration settings for the project are now settable. A build directory can now be specified, which defaults to the build sub-directory created off of the project’s main directory. For newlib, specify the special --with-newlib option when building on the native platform; otherwise, building does nothing as it is assumed that glibc is used.

Once the configuration settings are done, build the project. Run configure to generate the Makefile. The Autotools plug-in adds a special Makefile builder to the build process that performs the configuration step just prior to invoking make to build. Initiate the build step via the Project menu Build Project action, as demonstrated in Figure 2.

After the build is complete, an additional console is available that contains the results of the configuration step, as shown in Figure 3. These results are useful for analyzing any configuration decisions that may affect the build. For example, it shows when the configuration step chooses the wrong compiler due to the execution path. The console can be displayed by clicking on the Console icon in the console window. Clicking on the down arrow beside it shows the other consoles that are available.

As part of the Autotools plug-in, a default Gnu C/C++ error parser is designated. This parser gets invoked on the results of the GNU make invocation and is used to determine errors and warnings, as shown in Figure 4. For example, it finds any gcc compile errors and warnings, and parses the file name and the line number plus the error/warning message. The parser places all of that data in a visual format found via the Problems tab. In the Problems tab view, double-clicking on any of the errors or warnings brings up the file in question, highlighting the line where the error or warning occurred.

Note: The CDT Project Menu build action is set up for basic projects that have simple Makefile targets. The simple targets are all and clean. This may be sufficient some of the time, however, there are many make targets commonly needed for an open source project. For example, many open source projects have a distinct make target to install the project. There is also the matter of generating documentation, running test suites, building sub-components of the project, and so forth.

To build the various targets that are available, use the new menu item Build Special Targets in the Project menu, as shown in Figure 5. This menu item is only activated for an Autotools project. Clicking the item brings up the Build Special Targets dialog that represents the top-level Makefile as an alphabetic list of targets. Scroll down the list and click on a specific target. A faster method uses the text entry field to narrow down the list by the letters typed. If a target is chosen, make is run for that target.

To browse the source code, pick a C source file through the Navigator view. Click through the tree to find the file, then double-click it. This opens the file in the editor window and creates an outline view in the Outline window. To see the source for the included header files, the Autotools plug-in has special logic to parse the compile command used to build the C source file and extract the final include path plus any define flags. This allows selecting a header file for viewing by double-clicking its name in the Outline view. The Autotools plug-in uses the calculated include path to determine what the first include file (of the given name) is to be found on the path. This is very helpful in diagnosing errors and warnings, as the project may not be including the expected header file.

When a header file also includes another header file, Autotools treats such a nested header file the same as it did for the first-level header file. It uses the include path and define symbols from the originating C/C++ source file.

These attributes get chained together to handle any number of nested levels. It is dependent on the originating source file. If a header file is needed in the context of a different source file, the new source file must be opened and then the header file must be reached by double-clicking in the Outline view again. At present, there is no way to see a header file in multiple contexts. Opening a header file directly from the Navigator does not have a source-context and the Project static include path and project directories might have to be searched. If the header file exists in multiple places for such a search, a dialog pops-up that displays the possible choices.

An interesting feature of the CDT is that even with indexing off, the CDT analyzes the source code when it displays an outline in the Outline view. This analysis is not extensive but incorporates knowledge of external defined symbol flags as well as macros defined within that file, shown in Figure 6.

In the example with newlib, an existing project was checked out then converted. There is an alternative way of getting an Autotools project during check-out, which is demonstrated in Figure 7. When checking the code out using Eclipse, select to bring up a Project Wizard during check-out. In the case of Autotools, choose the Managed Make Project Wizard. The Autotools project is based upon the Managed Make project. In the Managed Make Project Wizard, select the type of project. One of the choices available is Autotools, and selecting that eliminates the need for a separate conversion step.

This project example demonstrates other interesting features of Autotools. In the default mode, when rebuilding, the configuration step is fast-tracked using the top-level config.status, meaning the project is not manually configured each time. Changing the configuration for a single build is done through the Project Properties menu under configuration settings, shown in Figure 8. When the changes are confirmed using the Apply or Ok buttons, the Autotools plug-in compares the new configuration to the old one. If any change has been made, a subsequent build causes full configuration to occur.

For helping in coding C Library functions, hover help has been added. The hover help is generated from the glibc documentation, so is glibc-specific. Hold the cursor over a library function, such as printf, and the prototype and brief description appears, shown in Figure 9.

To aid in analyzing Autotool projects, online help has been added for various gnu tools. These include gcc, binutils, automake, and autoconf. Go to the menu Help => Help Contents => Gnu Tools.

About the author

Jeff Johnston has been employed by Red Hat since 1997 when Red Hat acquired Cygnus Solutions. Working in Toronto, he is currently a member of the Eclipse team at Red Hat, developing the CDT Autotools Plug-in. Jeff has worked on a number of projects in his tenure at Red Hat including: the sid simulator, gdb, and the newlib embedded C Library, for which he is the head maintainer. Outside of work, Jeff plays keyboards and is an aspiring composer of light progressive rock. His band, Vermillion Skye, is currently recording their third CD.