This document describes the proposed work items for the scanner configuration usability enhancements for the CDT 2.0 release.
| Scanner
Configuration Usability Enhancements SRS This document describes the proposed work items for the scanner configuration usability enhancements for the CDT 2.0 release. |
|
| Author | : Vladimir Hirsl |
| Revision Date | : 12/14/2003 - Version: 0.1.0 |
| Change History | : 0.1.0 - Document Creation |
A common complaint from 1.2 users is that search (along with the other 2 search clients - code completion and navigation) doesn't always seem to work properly. The cause is always invariantly the same; the user's project is not set up properly. Without specifying which directories to search for included files and what symbols are defined the parser quickly runs into trouble. As a result, the index is incomplete and search appears to fail.
One of the main focus points for the 2.0 release is improving the initial user experience; we want all features to work as well as possible right "out-of-the-box". In order to accomplish this, search needs to take some steps to ensure the project environment is set up properly.
Currently, all CDT projects are either Managed Make or Standard
Make.
Of the two types of projects, users will run into problems with search
in Standard Make projects. Managed Make projects require the user to
enter all of the paths/symbols needed in order to build. If a critical
path is missing, the project will not build. The parser, therefore, is
guaranteed to have all of the paths needed to properly index since the
build and parser settings are in the same
place. Standard make projects, on the other hand, don't require
the user to set up the include paths/symbols. All required build info
is in the user's makefiles. Thus, for the Standard make scenario,
Search needs to find a way to figure
out the include paths from the makefile.
The goal of this feature is to make it easy for users to configure the CDT scanner configuration so that indexer can produce reliable output for its clients (search, code assist, text hover, refactoring, etc) and therefore enhance CDT's usability.
This section defines terms commonly used in this document.
| Build target | A target in the build sense as
defined in makefiles (i.e. clean, all) |
| Scanner configuration |
A collection of include paths
and symbol definitions used by the compiler to process a compilation
unit (i.e
.c or .cpp file). On a project level it is defined as a union of all
project's compilation units' scanner configurations. |
| Indexer |
Provider of information needed
for efficient searching, code assist, text hover, refactoring, etc.
Relies heavily on the parser/scanner. |
| Number |
Description |
| C1 |
Conflicting
include paths or symbol definitions Include paths or symbol definitions may be different for each compilation unit, and if stored collectively at the project level, may lead to scanner errors or ambiguities in some cases. This is a known limitation of this feature. |
List of requirements for scanner configuration usability enhancements is classified into following categories:
| Number |
Priority |
Description |
| R1 |
P1 |
Automate
discovery of
project's scanner configuration
In CDT release 1.2, the only way
to define project's scanner
configuration is by entering individual entries for include paths and
symbol definitions through GUI. Assuming that the project builds
successfully, this information is already available in the build
environment and project's makefiles, since compiler uses it to process
source files. Ideally, the information available to the compiler should
be captured and entered into project's scanner configuration to be used
by the Indexer.
|
| R2 |
P1 |
User shall be able to turn on/off automated discovery of project's scanner configuration |
| R3 |
P1 |
User shall be able to cancel scanner configuration discovery in progress if it takes a noticeable time to complete |
| R4 |
P1 |
User
shall be able to contribute to a project's scanner configuration Regardless of the automated scanner configuration discovery, user shall be able to define include paths and symbol definitions through GUI (as currently possible). If automated scanner configuration discovery is turned on, its results will be supplementary to the user's input. |
| R5 |
P2 |
Continuous
discovery of project's scanner configuration Project's scanner configuration shall be continuously updated. Changes in project's scanner configuration shall be reported to the Indexer. |
| R6 |
P2 |
Use
a previously performed nightly build logs as a source for scanner
configuration discovery User shall be able to provide a nightly build log file as an input to scanner configuration discovery. |
| Number |
Priority |
Description |
| R7 |
P1 |
User
shall be able to edit
discovered scanner configuration User has an option to edit, correct or remove items from the discovered scanner configuration. User preferences should be persisted so that user does not have to redo them each time scanner configuration is rediscovered or updated. |
| R8 |
P1 |
Enable
management of
project's scanner configuration in team environment
|
| R9 |
P1 |
Management of project's scanner configuration shall be compiler independent |
| R10 |
P1 |
Relative
include paths shall be
properly handled (no silent failure) User shall be presented with an option to convert relative include paths into absolute include paths or variable extended paths. |
| R11 |
P1 |
Scanner
configuration shall be accessible to other CDT subsystems It should be easy to identify and correct problems in the scanner configuration. For example if a header file or a symbol definition cannot be found it should be possible to access scanner configuration and alter it so that a problem can be fixed. |
| R12 |
P2 |
Multiple
scanner configurations Similar to build configuration in managed make projects, user should be able to define multiple scanner configurations for a standard make project. The automated scanner configuration discovery then should apply to an active scanner configuration. |
| Number |
Priority |
Description |
| R13 |
P1 |
Discovery of scanner configuration shall work for most home-grown Makefile environments, including very large projects |
| R14 |
P1 |
Minimal or no impact to creating a Standard Make Project from scratch |
| R15 |
P1 |
Minimal or no impact to creating a Managed Make Project from scratch |
| |