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

This tutorial needs a review. You can edit it in GitHub following these contribution guidelines.
netbeans stamp
Figure 1. Content on this page applies to the NetBeans IDE 8.0

To follow this tutorial, you need the following software.

Software Version Required

NetBeans IDE (including C/C++ support)

Version 8.0

Java Development Kit (JDK)

Version 7 or 8

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

Introduction

This tutorial demonstrates how to edit existing tool collections or create a custom version of an existing tool collection in NetBeans IDE 8.0.

The example shown applies to the GNU tool collection for Oracle Solaris and Linux, but the concepts can also apply to Windows and Mac. Using this information you can learn how to do the following:

  • Change compiler flags that the IDE uses by default for compiling C/C++ files

  • Add a compiler that is not supported by the IDE

Tool Collections

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

The tool collection descriptor is an XML file located in the module IDE_HOME/cnd/modules/org-netbeans-modules-cnd-toolchain.jar in the folder org/netbeans/modules/cnd/toolchain/resources/toolchaindefinition/ . You should not edit these original IDE tool descriptor XML files.

This article tells you how to create duplicates of the tool descriptors in your own NetBeans user directory that you can edit. The IDE will then use the information in the tool collection descriptors located in your user directory instead of the original versions.

Community-Contributed Tool Collections

Some plugins for tool collections have been contributed by users in the NetBeans community:

Note that these plugins are not officially supported but are referenced here in case you find them helpful in creating your own plugins.

Windows users might also be interested in an article from a user in the NetBeans community: NetBeans Setup and GNU Cross-Toolchain Configuration for ARM Development.

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. This section describes how to make duplicate "shadow" copies of the tool collection descriptors which you can edit to change the way the IDE uses the tools.

  1. Exit the IDE if it is running.

  2. Edit the file IDE-HOME/etc/netbeans.conf , where IDE-HOME is the NetBeans installation directory.

  3. Add the following flag to the netbeans_default_options entry:

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

  1. Start the IDE, choose Tools > Options, and select C/C++ in the top pane of the Options window.

The IDE creates a directory containing "shadow" versions of the tool collection descriptors in your NetBeans user directory:

userdir

/config/CND/ToolChain

The location of your NetBeans user directory varies according to your operating system. Some possible locations of the userdir/config/CND/ToolChain directory include:

  • Windows: C:\Documents and Settings_username_\Application Data\NetBeans_version_\config\CND\ToolChain

  • Mac: /Users/username/Library/Application Support/NetBeans/version/config/CND/ToolChain

  • Linux and Solaris: /home/username/.netbeans/version/config/CND/ToolChain

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

CLang.xml                             SunStudio.xml
CLang_mac.xml                         SunStudio_10.xml
CLang_solaris.xml                     SunStudio_11.xml
Cygwin.xml                            SunStudio_12.1_solaris-sparc.xml
Cygwin_4.x.xml                        SunStudio_12.1_solaris-x86_linux.xml
GNU.xml                               SunStudio_12.2_linuxCompatGNU.xml
GNU_mac.xml                           SunStudio_12.2_solaris-sparc.xml
GNU_solaris.xml                       SunStudio_12.2_solaris-x86_linux.xml
Intel.xml                             SunStudio_12.3_linuxCompatGNU.xml
Interix.xml                           SunStudio_12.3_solaris-sparc.xml
MinGW.xml                             SunStudio_12.3_solaris-x86_linux.xml
MinGW_TDM.xml                         SunStudio_12.xml
OSS_linuxCompatGNU.xml                SunStudio_8.xml
OSS_solaris-sparc.xml                 SunStudio_9.xml
OSS_solaris-x86_linux.xml             WinAVR.xml
OracleSolarisStudio.xml

You can edit the descriptor for the toolchain you are using. For example, if you are using GNU on Solaris, edit the GNU_solaris.xml file; if you are using MinGW on Windows, you should edit the MinGW.xml file.

For information about the tags used in these descriptor XML fies, see Details for the Tool Collection XML File. You can change the values for the tags to change the behavior of the tools in the IDE.

The descriptors in this directory take precedence over the official versions in the IDE-HOME directory. You should delete the tool descriptors in your user directory that you do not want the IDE to use.

  1. Remove the -J-Dcnd.toolchain.personality.create_shadow=true flag from the IDE-HOME/etc/netbeans.conf so the IDE does not create shadow descriptors again.

  1. Restart the IDE to use the modified tool descriptor when you are finished making changes.

Creating a Custom Tool Collection

This section shows how to create a tool collection that is based on the GNU tool collection with some changes to compiler flags for debugging. The example shows steps for creating a new NetBeans module that contains a new tool collection to enable you to share the tool collection or use it in other instances of the IDE.

For general information about creating NetBeans modules, see NetBeans Plugin Quick Start.

To create a custom tool collection:

  1. Make sure your NetBeans installation includes the NetBeans Plugin Development module.

Choose Tools > Plugins and click 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.

  1. 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.

  1. On the Name and Location page, type the project name, for example mytoolchain and leave all other fields as is. Click Next.

  1. On the Basic Module Configuration page, type org.myhome.mytoolchain for Code Name Base, which defines the unique string identifying the module you are creating. The code name base is also used as the main package of the module.

  1. Do not select the "Generate OSGi Bundle" checkbox, since you will be using the default NetBeans module system, rather than OSGi.

  1. Click Finish. The IDE creates a new project named mytoolchain.

  1. In the Projects tab, right click the mytoolchain project node and select New > Other.

  1. In the New File wizard, select the category Module Development and the file type XML Layer, then click Next and click Finish.

The IDE creates layer.xml under the Source Packages node, inside the main package org.myhome.mytoolchain and opens layer.xml in the editor.

  1. If the file contains a <filesystem/> tag, replace it with opening and closing filesystem tags: <filesystem>

 ``</filesystem>``

  1. Copy and paste the following text in layer.xml 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>

  1. Open the Bundle.properties file and add the following string: CND/ToolChains/GNU_tuned=My GNU Tuned Tool Collection

  1. Create the subpackage toolchain by right-clicking the org.myhome.mytoolchain package under Source Packages and selecting New > Java Package. Replace the default package name newpackage with toolchain and click Finish. The IDE creates the subpackage org.myhome.mytoolchain.toolchain .

  1. Create a new file by right-clicking the org.myhome.mytoolchain.toolchain subpackage and selecting New > Empty File. Name the file GNU_tuned_flavor.xml and click Finish.

If you do not see Empty File as an option, select Other and then in the New File wizard, select the category Other and the file type Empty File and click Next.

This file is the tool collection descriptor for the new tool collection.

  1. Copy and paste the following text in GNU_tuned_flavor.xml :

<?xml version="1.0" encoding="UTF-8"?>
<toolchaindefinition xmlns="https://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>

  1. Create another new file by right-clicking the org.myhome.mytoolchain.toolchain subpackage and selecting New > Empty File. Name the file GNU_tuned_cpp.xml and click Next.

  1. Copy and paste the following text in GNU_tuned_cpp.xml :

<?xml version="1.0" encoding="UTF-8"?>
<toolchaindefinition xmlns="https://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 should look similar to the following:

project
Figure 2. Project tree

The Unit Test folders might not exist.

  1. 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.

  1. In the running module, choose Tools > Options, select C/C++ from the top pane of the Options window, and select the Build Tools tab.

  1. 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:

options
Figure 3. Options panel

  1. Create a new C/C sample project ``Welcome`` by selecting File > New Project > Samples > C/C > Welcome.

  1. 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.

  1. 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

  1. In the Project Properties dialog box, select the GNU tool collection and click OK.

  1. 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

You should be able to see that the GNU_tuned tool collection has different 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 Defaults. 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 search for the file toolchaindefinition.xsd in the NetBeans IDE source tree .

Tool collection definition tags

Tags Attributes Description

toolchain

Name of tool collection

name

Name of tool collection

display

Display name of tool collection

family

Group name of tool collection

platforms

Supported platforms

stringvalue

List of supported platforms separated by comma.

Possible values are:

* linux * unix * sun_intel * sun_sparc * windows * mac * none

makefile_writer

Custom makefile writer.

class

Class name of custom makefile writer. It should implement org.netbeans.modules.cnd.makeproject.spi.configurations.MakefileWriter.

drive_letter_prefix

Special prefix for file names

stringvalue

"/" for unix "/cygdrive/" for cygwin on Windows

base_folders

Container for base_folder tags. One or more base_folder tags are contained in one base_folders tag.

base_folder

Description of base directory for compilers. This tag can contain the following tags:

regestry

Windows registry key of the tool. Note that the XML tag must be spelled "regestry" although this is a mispelling.

pattern

Regular expression that allows NetBeans IDE to find compiler in registry

suffix

Folder with executable files

path_patern

Regular expression that allows NetBeans IDE to find compiler by scanning paths. Note that the XML tag must be spelled "path_patern" although this is a mispelling.

command_folders

Container for command_folder tags. One or more commander_folder tags are contained in one command_folders tag.

command_folder

Describes the directory where UNIX-like commands are located. Only needed for MinGW compiler on Windows. The command_folder tag can contain the following tags:

regestry

Windows registry key of commands. Note that the XML tag must be spelled "regestry" although this is a mispelling.

pattern

Regular expression that allows NetBeans IDE to find the commands folder in the registry

suffix

Folder with executable files

path_patern

Regular expression that allows NetBeans IDE to find commands. Note that the XML tag must be spelled "path_patern" although this is a mispelling.

scanner

Name of error parser service, see Creating a Custom Compiler Error Handler

Compiler flags

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

Tags Description Example for GNU compiler

c,cpp

Set of compiler flags are located in following sub nodes

recognizer

Regular expression that allows the IDE to find compiler

For GNU under cygwin on Windows .[\\/].*cygwin.[\\/]bin[\\/]?$

compiler

Compiler name (name of executable file)

gcc or g++

version

Version flag

--version

system_include_paths

Flags to get system include paths

-x c -E -v

system_macros

Flags to get system macros

-x c -E -dM

user_include

Flag to add user include path

-I

user_file

Flag to include the contents of file before other files

-include file

user_macro

Flag to add user macro

-D

development_mode

Groups of flags for different development modes

warning_level

Groups of flags for different warning level

architecture

Groups of flags for different architecture

strip

Flag for stripping debug information

-s

c_standard

Specifies the flags to use for C standards. Use with c89, c99 and c11 tags.

c89 flags="-std=c89" c99 flags="-std=c99" c11 flags="-std=c11"

cpp_standard

Specifies the flags to use for C++ standards. Use with cpp98 and cpp11 tags.

cpp98 flags="-std=c98" cpp11 flags="-std=c11" cpp11 flags="-std=gnu++0x"

output_object_file

Flags for specifying object file

-o (must have a space following -o)

dependency_generation

Flags for dependency generation

-MMD -MP -MF $@.d

precompiled_header

Flags for precompiled header

-o $@

important_flags

Regular expression that specifies which compiler flags change default system include paths and predefined macros for code assistance

-O1

-O2

-O3

-O4

-O5

-Ofast

-Og

-Os

-ansi

-fPIC

-fPIE

-fasynchronous-unwind-tables

-fbuilding-libgcc

-fexceptions

-ffast-math

-ffinite-math-only

-ffreestanding

-fgnu-tm

-fhandle-exceptions

-fleading-underscore

-fno-exceptions

-fno-rtti

-fnon-call-exceptions

-fnon-call-exceptions

-fopenmp

-fpic

-fpie

-fsanitize=address

-fshort-double

-fshort-wchar

-fsignaling-nans

-fstack-protector(\W

$

-)

-fstack-protector-all

-funsigned-char

-funwind-tables

-g(\W

$

-)

-ggdb

-gsplit-dwarf

-gtoggle

-m128bit-long-double

-m3dnow

-m64

-mabm

-madx

-maes

-march=.*

-mavx

-mavx2

-mbmi

-mbmi2

-mf16c

-mfma(\W

$

-)

-mfma4

-mfsgsbase

-mlong-double-64

-mlwp

-mlzcnt

-mpclmul

-mpopcnt

-mprfchw

-mrdrnd

-mrdseed

-mrtm

-msse3

-msse4(\W

$

-)

-msse4.1

-msse4.2

-msse4a

-msse5

-mssse3

-mtbm

-mtune=.*

-mx32

-mxop

-mxsave

-mxsaveopt

-pthreads

-std=.*

-xc($

+\+$)

multithreading

Groups of flags for multithreading support

Only for Oracle Solaris Studio tool collection, not used in GNU-based tool collections

standard

Groups of flags for different language standards

Only for Oracle Solaris Studio tool collection, not used in GNU-based tool collections

language_extension

Groups of flags for different language extensions

Only for Oracle Solaris Studio tool collection, not used in GNU-based tool collections

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>

See Also

Please see the C/C++ Learning Trail for more articles about developing with C/C++/Fortran in NetBeans IDE.

Send Us Your Feedback