Using the C/C++ Tool Collection Descriptor - NetBeans IDE 6.9 Tutorial

Contents

• Introduction
• Tool Collections
• Editing Tool Collection Descriptors
• Creating a Custom Tool Collection
• Details for the Tool Collection XML File
• Creating a Custom Compiler Provider
• Creating a Custom Compiler Error Handler

To follow this tutorial, you need the following software.

See the NetBeans IDE 6.9 Installation Instructions and Configuring the NetBeans IDE for C/C++/Fortran
for information about downloading and installing the required software.

Introduction

Do you want to change compiler flags that the NetBeans IDE uses by default for compiling C/C++ files? Do you want to add a compiler that is not supported by the NetBeans IDE? This article can help you to do this! This tutorial demonstrates how to edit existing tool collections or create a custom tool collection in NetBeans IDE 6.9.

Tool Collections

A tool collection is a set of compilers, make utility, and debugger. Every time you compile, make, or debug your code, the NetBeans IDE runs an executable file described in the tool collection descriptor. Code Assistance features use include paths and macros taken from the tool collection.

The tool collection descriptor is an xml file located in the module ${NB}/cnd/modules/org-netbeans-modules-cnd-toolchain.jar in the folder org/netbeans/modules/cnd/toolchain/resources/toolchaindefinition/. You should not edit these original NetBeans tool descriptor xml files. This article tells you how to create duplicates that you can edit.

Editing Tool Collection Descriptors

Editing a tool collection descriptor is a bit tricky since the NetBeans IDE does not provide a GUI for editing descriptors. But here we describe how to make dupluicate "shadow" copies of the tool collection descriptors to enable you to edit them to change the way the IDE uses the tools.

1. Exit the IDE if it is running.
2. Add the following flag to the netbeans_default_options entry in the file ${NB}/etc/netbeans.conf:

   -J-Dcnd.toolchain.personality.create_shadow=true

3. Start the IDE, choose Tools > Options, and select C/C++ in the top pane of the Options window. The IDE creates "shadow" versions of the tool collection descriptors in your user directory:

   ${userdir}/config/CND/ToolChain

   The list of descriptors created should be similar to the following:

   Cygwin.xml		GNU_solaris.xml		SunStudio.xml		SunStudio_12.1.xml	SunStudio_Linux.xml
   Cygwin_4.x.xml		Interix.xml		SunStudioExpress.xml	SunStudio_12.xml
   GNU.xml			MinGW.xml		SunStudio_10.xml	SunStudio_8.xml
   GNU_mac.xml		MinGW_TDM.xml		SunStudio_11.xml	SunStudio_9.xml
   

4. You can edit the descriptor for the toolchain you are using, and the IDE will use the descriptor after you restart. See the Details for the Tool Collection XML File for information about the tags used in these descriptor XML fies.

Remove the -J-Dcnd.toolchain.personality.create_shadow=true flag before you start IDE next time. The IDE needs only once to create the shadow descriptors.

Creating a Custom Tool Collection

You can create your own tool collection. The following example creates a new NetBeans module that contains a new tool collection. For general information about creating NetBeans modules, see NetBeans Plugin Quick Start.

1. Make sure your NetBeans installation includes the NetBeans Plugin Development module by choosing Tools > Plugins and clicking the Installed tab. If the NetBeans Plugin Development module is not installed, click the Available Plugins tab and install the module. You can find it quickly by typing "plugin" in the Search box.
2. Create a new NetBeans module by choosing File > New Project. On the Choose Project page of the New Project wizard, select the category NetBeans Modules and the project Module in the first step of the wizard. Click Next.
3. On the Name and Location page, type the project name, for example mytoolchain and leave all other fields as is. Cick Next.
4. On the Basic Module Configuration page, type the code name base, for example org.myhome.mytoolchain, and select the check box Generate XML Layer. Click Finish. The IDE creates a new project.
5. Find the file layer.xml in the Projects window, under the Source Packages node. Double-click the layer.xml file to open it in the editor.
6. Copy and paste the following text inside the filesystem tag:

   <folder name="CND">
           <folder name="Tool">
               <file name="GNU_tuned_flavor" url="toolchain/GNU_tuned_flavor.xml">
                   <attr name="extends" stringvalue="GNU_flavor"/>
               </file>
               <file name="GNU_tuned_cpp" url="toolchain/GNU_tuned_cpp.xml">
                   <attr name="extends" stringvalue="GNU_cpp"/>
               </file>
           </folder>
           <folder name="ToolChains">
               <folder name="GNU_tuned">
                   <attr name="position" intvalue="5000"/>
                   <attr name="SystemFileSystem.localizingBundle" stringvalue="org.myhome.mytoolchain.Bundle"/>
                   <file name="flavor.shadow">
                       <attr name="originalFile" stringvalue="CND/Tool/GNU_tuned_flavor"/>
                   </file>
                   <file name="c.shadow">
                       <attr name="originalFile" stringvalue="CND/Tool/GNU_c"/>
                   </file>
                   <file name="cpp.shadow">
                       <attr name="originalFile" stringvalue="CND/Tool/GNU_tuned_cpp"/>
                   </file>
                   <file name="fortran.shadow">
                       <attr name="originalFile" stringvalue="CND/Tool/GNU_fortran"/>
                   </file>
                   <file name="assembler.shadow">
                       <attr name="originalFile" stringvalue="CND/Tool/GNU_assembler"/>
                   </file>
                   <file name="scanner.shadow">
                       <attr name="originalFile" stringvalue="CND/Tool/GNU_scanner"/>
                   </file>
                   <file name="linker.shadow">
                       <attr name="originalFile" stringvalue="CND/Tool/GNU_linker"/>
                   </file>
                   <file name="make.shadow">
                       <attr name="originalFile" stringvalue="CND/Tool/GNU_make"/>
                   </file>
                   <file name="debugger.shadow">
                       <attr name="originalFile" stringvalue="CND/Tool/GNU_debugger"/>
                   </file>
                   <file name="qmake.shadow">
                       <attr name="originalFile" stringvalue="CND/Tool/GNU_qmake"/>
                   </file>
                   <file name="cmake.shadow">
                       <attr name="originalFile" stringvalue="CND/Tool/GNU_cmake"/>
                   </file>
               </folder>
           </folder>
       </folder>
       

7. Open the Bundle.properties file and add the following string:
   CND/ToolChains/GNU_tuned=My GNU Tuned Tool Collection
8. Create the subpackage toolchain by right-clicking the mytoolchain package under Source Packages and selecting New > Java Package.
9. Create a new file in the toolchain package by right-clicking the toolchain subpackage and selecting New > Empty File. Name the file GNU_tuned_flavor.xml and click Next.
10. Copy and paste the following text in GNU_tuned_flavor.xml:

    <?xml version="1.0" encoding="UTF-8"?>
    <toolchaindefinition xmlns="http://www.netbeans.org/ns/cnd-toolchain-definition/1">
        <toolchain name="GNU_tuned_flavor" display="GNU_tuned" family="GNU" qmakespec="${os}-g++"/>
        <platforms stringvalue="linux,sun_intel,sun_sparc"/>
    </toolchaindefinition>
    

11. Create another new file in the toolchain package by right-clicking the toolchain subpackage and selecting New > Empty File. Name the file GNU_tuned_cpp.xml and click Next.
12. Copy and paste the following text in GNU_tuned_cpp.xml:

    <?xml version="1.0" encoding="UTF-8"?>
    <toolchaindefinition xmlns="http://www.netbeans.org/ns/cnd-toolchain-definition/1">
        <cpp>
            <compiler name="g++"/>
            <development_mode>
                <fast_build flags=""/>
                <debug flags="-g3 -gdwarf-2" default="true"/>
                <performance_debug flags="-g -O"/>
                <test_coverage flags="-g"/>
                <diagnosable_release flags="-g -O2"/>
                <release flags="-O2"/>
                <performance_release flags="-O3"/>
            </development_mode>
        </cpp>
    </toolchaindefinition>
    

    Notice the debug flags are set to -g3 and -gdwarf-2, which are different from the flags set in the default GNU tool collection description.
    The project tree looks like the following:
    
    
    
13. In the Projects window, right-click the mytoolchain project node and choose Run. The module is built and installed in a new instance of the IDE, which is the default target platform of modules. The target platform opens so that you can try out the new module.
14. In the running module, choose Tools > Options, select C/C++ from the top pane of the Options window, and select the Build Tools tab.
15. If the new tool collection (GNU_tuned) is not shown, click Restore Default. Click Yes to continue when prompted to rescan your environment. The IDE shows the new tool collection:
    
    
    
16. Create a new C/C++ sample project Welcome by selecting File > New Project > Samples > C/C++ > Welcome.
17. Right-click the project node and choose Properties. In the Project Properties dialog box, select the Build node, set the Tool Collection to your GNU_tuned tool collection and click OK.
18. Build the project. Note that the compiler has flags -g3 -gdwarf-2

    g++ -c -g3 -gdwarf-2 -MMD -MP -MF build/Debug/GNU_tuned-Solaris-x86/welcome.o.d -o build/Debug/GNU_tuned-Solaris-x86/welcome.o welcome.cc

In the Project Properties dialog box, select the GNU tool collection and click OK.
19. Build the project again, and compare the compile line in the output window:

    g++ -c -g -MMD -MP -MF build/Debug/GNU-Solaris-x86/welcome.o.d -o build/Debug/GNU-Solaris-x86/welcome.o welcome.cc

So in the GNU_tuned tool collection, we have managed to change compiler flags for debug, Development Mode for the GNU compiler.

If you want to use the new module for the GNU_tuned tool collection in your regular IDE, you can create a binary (a .nbm file) and add it as a plugin:

1. Right-click the mytoolchain module project and select Create NBM. The .nbm file is created in the build subdirectory of the project, which you can see in the Files tab.
2. Select Tools > Plugins, then click the Downloaded tab in the Plugins dialog box.
3. Click Add Plugins, navigate to the build directory, select the module .nbm file, and click Open. The plugin module is added to the list in the Downloaded tab.
4. Click the checkbox to select the module in the Downloaded tab, then click the Install button. The NetBeans Plugin Installer opens.
5. Click Next to advance through the installer, and continue until the installer is finished.
6. Restart the IDE, and then choose Tools > Options, select C/C++ from the top pane of the Options window, and select the Build Tools tab.
7. If the new tool collection (GNU_tuned) is not shown, click Restore Default. Click Yes to continue when prompted to rescan your environment.

Details for the Tool Collection XML File

This is a description of most important tags in the tool collection xml file.

For the scheme of all supported tags and attributes of toolchain xml files, you can refer to the file toolchaindefinition.xsd in the NetBeans IDE 6.9 source tree.

Tool collection definition tags

Compiler flags

This table lists the tags used to describe the compilers and specify compiler flags for the toolchain.

Creating a Custom Compiler Provider

NetBeans IDE has a default compiler provider:
org.netbeans.modules.cnd.toolchain.compilers.MakeProjectCompilerProvider
This provider works well enough for most toolchains, but you can also create own provider.

To create your own compiler provider:

• extend abstract class org.netbeans.modules.cnd.api.compilers.CompilerProvider
• define class as service and put it before default provider:

  @org.openide.util.lookup.ServiceProvider(service = org.netbeans.modules.cnd.spi.toolchain.CompilerProvider.class,
  position=500)
  public class CustomCompilerProvider extends CompilerProvider {
  ...
  }
  

  The position=500 attribute guarantees that the custom provider will be invoked before the default provider. The custom provider should return not NULL "Tool" in method "createCompiler()" for tool that should be overridden.

Creating a Custom Compiler Error Handler

NetBeans IDE has a two default compiler error handlers.

• for GNU compiler
• for Sun Studio compiler

The GNU compiler handler works well enough for any GNU compiler, but if you want you can define your own compiler error handlers.

To create your own compiler error handler:

• extend abstract class org.netbeans.modules.cnd.spi.toolchain.CompilerProvider
• define class as service:

  @org.openide.util.lookup.ServiceProvider(service = org.netbeans.modules.cnd.spi.toolchain.CompilerProvider.class)
        public class CustomCompilerProvider extends ErrorParserProvider {
            ...
            @Override
            public String getID() {
        	return "MyParser";  // NOI18N
            }
        }

• link error scanner and tool collection description by ID:

  </scanner id="MyParser">
  ...
    </scanner>