If you are creating a project from existing code, then in most cases, there
is a simple recipe for configuring code assistance:
build your code with extended debugging information
(-g3 -gdwarf-2 compiler flags)
before creating the project.
For open source projects (and for most other projects as well),
you can generate the extended debugging information by building the code as
follows:
./configure CFLAGS="-g3 -gdwarf-2" CXXFLAGS="-g3 -gdwarf-2"
make
or
make CFLAGS="-g3 -gdwarf-2" CXXFLAGS="-g3 -gdwarf-2"
After building with these options, when you create a project from the code,
the IDE configures code assistance automatically
using the extended debugging information from binary or object files.
Did you forget to build your code with options for extended debugging information
before creating a project from it? No problem.
You can build the project with these options later, then right-click the
project in the Projects window, choose
Code Assistance > Configure Code Assistance, accept all defaults, and click
Finish.
Try it. If it works, and you aren't interested in deep diving,
you probably won't want to read the rest of this tutorial.
Still have issues? Want to know more? Then read further.
What is Code Assistance? Why Should I Configure It?
Code assistance is a set of IDE features that help you navigate and edit source code:
code completion, search for usages, hyperlinking to declaration, viewing current file structure
in the Navigator window,
investigating a class inheritance hierarchy, viewing
header's include hierarchy, viewing a type hierarchy, and so on.
If your project has code assistance configuration issues
these features do not work well.
What is the Problem?
There are two kind of C/C++ projects in the NetBeans IDE: managed projects
and projects from existing code.
A managed project is a project you create "from scratch" using the IDE
(i.e., in the New Project wizard you select C/C++ Application,
C/C++ Static Library, or C/C++ Dynamic Library). The IDE knows everything about
such a project and generates the makefile for the project. So you do not need
to configure code assistance in this case.
The situation is quite different when you create a project from existing code.
In this case the IDE uses the makefile you specify to build the project.
It initially knows nothing about which particular files should be compiled
and which compiler options should be used.
For code assistance to work properly with a project from existing code,
it should "know" what compiler options should be used for each file
(-I and -D options are of most interest).
If it does not, it might not understand your code correctly.
There are several ways of configuring code assistance automatically;
we'll cover this a bit later.
How Do I Know That I have Code Assistance Configuration Issues?
Two indicators show that your project has code assistance configuration
issues:
The first indicator is a small question mark on your project icon in the
Projects window.
In the image below, the clucene-0.9.10-3 project is misconfigured.
This question mark appears when code assistance cannot resolve at least one
#include directive.
In your source code you'll see #include directives
that the IDE couldn't resolve underlined with red:
In this case you will sometimes notice that the wrong conditional branch is
grayed out.
For example, you know that the LUCENE_ENABLE_MEMORY_POOL1 macro is
defined, so the code
at the iamge above should not be grayed out.
Why does this happen? The reason is that the IDE does not "know"
that your current file should be compiled as follows:
The lack of this knowledge does not prevent the IDE from building your
project correctly
To see the full list of #include directives
that the IDE couldn't resolve, right-click the project in the Projects window
and choose Code Assistance > Show Failed #include Directives.
What Can I Do If My Project has Code Assistance Configuration Issues?
To configure your project after you have created it,
right-click the project and choose Code Assistance > Configure Code Assistance.
Simple vs Advanced Mode
The first page of the Configure Code Assistance wizard offers two modes:
Simple and Advanced.
In Simple mode, the IDE configures code assistance almost silently,
asking you for minimal information to use in determining the correct parsing options..
This mode suits most cases.
For example, if you forgot to build your code with -g3 -gdwarf-2 options
before creating the project, build it with these options afterwards and then
use the Configure Code Assistance wizard in Simple mode.
But you have less control in this case.
Advanced mode gives you more control.
In particular, it allows you to specify which source of information to use for
configuration.
Sources of information
The IDE can configure code assistance automatically using the following
sources of information (you can select one in the Advanced mode; in Simple
mode, the IDE selects one automatically),
Exploring executable or library file
If compiled with -g3 -gdwarf-2 options,
your binaries' (executable and libraries files)
debug information contains most of the information the IDE needs to
configure code assistance automatically.
If you use Sun Studio compilers, then just the -g
option is sufficient.
Exploring object files in folder
Same as the above; the only difference is that
object files in the project folder are searched for debug information
instead of executables or libraries.
Exploring make log
Often the build log contains enough information for the
IDE to determine the
necessary options (and the exact list of files
to be built).
To use this information source, save your build log in a file
and specify this file location in Configure Code Assistance wizard.
You can also do this
using a special button in the Output window.
Searching file system for C/C++ header files
This is a backup variant.
The IDE just searches the files in the location you specify
(by default it's a project folder)
and tries to resolve #include directives.
The drawback of this mode is that it does not help the IDE
to determine correct defines (-D options)
your project was built with.
Selecting a Configuration Level
The proper compiler options are determined per file.
The question is, how to store this information for a project -
per file, per folder, or per project.
Configure File Properties
This is the most precise configuration, which is why it is the default.
The drawback is that if you later want to change options manually,
you have to do so per file as well.
Configure Project Properties
Consolidates all options up to the project level, which makes it
convenient to maintain these options manually
(for those who'd like to - usually there is no necessity to do so).
Configuring Folder Properties
A compromise between the two above.
Configuring Code Assistance from the Output Window
After you run Clean and Build on your project,
the Configure Code Assistance button appears in the Output Window.
If you click this button, the IDE uses the current build log
to configure your project.
Configuring Code Assistance in Project Configurations
Your project can contain several configurations, for example, Debug and
Release;
or it can have additional configurations on a per-platform basis.
When you configure code assistance, you always alter only the
active (i.e., currently selected) configuration.
If you have multiple project configurations
and relevant compiler options (mostly -I and -D options)
are different for these configurations, you have to configure code assistance
separately for each configuration.
Configuring Code Assistance Manually
If you know the compiler options with which your project is being built,
you probably want to just specify them manually.
You can do this when you create the project.
On the Code Assistance Configuration page of the New Project wizard, select
Manual Configuration
and enter the Include Directories and Macro Definitions paths.
Or you can do it later.
Right-click the file, folder, or project in the Projects window and choose
Properties.
For a file or folder, select the C Compiler or C++ Compiler category and enter
the paths. For a project, select the Code Assistance category and then the C
Compiler or C++ Compiler category, and enter the paths.
