Imprint Privacy policy Terms & Conditions Sitemap

Eclipse C/C++ (CDT)

Data access

The Eclipse CDT data access provides access to C and C++ artifacts such as translation units or functions. It allows to store link information invasively, i.e., within comments in C or C++ files.

The blog post "Tracing requirements and source code" gives a general overview of identifying source code elements as traceable artifacts and linking them to other artifact types, e.g., requirements.

Configuration

Open the ANALYZE configuration with the ANALYZE configuration editor, and add a new data access as described in section "Data accesses". Select Eclipse CDT as data access type.

Within the configuration panel, you may specify file patterns consisting of Eclipse projects, folders or file name patterns describing the C/C++ files relevant for analysis.

Supported keyword:

  • resource – A pattern for a project, folder or file in the workspace.

The configuration may contain several resource definitions. In this case, ANALYZE takes the union of all patterns into account, i.e., the resource expressions are evaluated with a logical OR.

Independent of the definition of a resource, ANALYZE only takes files with suffixes .c, .h, or .cpp into account.

Please note: The resources have to reside in an Eclipse C/C++ project. Otherwise the CDT adapter will ignore these files, even when they match the pattern that was defined by using the resource keyword. You can create an Eclipse C/C++ project (for example) via a wizard that you can open by selecting New → Other... in the context menu of the „Package Explorer”. In that wizard, you can open the C/C++ tree and select C/C++ Project.

Example:

In this example, ANALYZE evaluates all .c and .h files in the folder named source in the com.itemis.analyze.mt.c project.

Indexer caveat

The CDT index supports searching and fast navigation in C files. This is achieved by resolving all links between files and caching them, aside from macros and active defines.

Initialization and maintenance of the index is not for free, and the CDT adapter finds artifacts even if the index is disabled. If the index is enabled, the option "Allow heuristic resolution of includes" can lead to problems with macros and other included references required to determine artifacts in the source code. In this case – or to prevent other problems –, this option should be disabled.

Artifact type

The C/C++ artifact type recognizes C/C++ elements such as translation units, include statements or functions in a specified set of relevant files. It does not recognize single statements within a function.

As rule-of-thumb, ANALYZE recognizes all elements that do appear in the Eclipse CDT’s outline view for C/C++ files.

Configuration

Open the ANALYZE configuration with the ANALYZE configuration editor, and add a new artifact type as described in section "Artifact types". Select your previously-configured Eclipse CDT data access in the Data access drop-down list.

Supported keywords:

  • model elements – The list of C/C++ element types to recognize as artifacts. An explicit comma-separated list of types can be specified, or one of the following keywords can be used for a predefined list of types:
    • all – Includes all C/C++ element types
    • default – Includes this default subset of C element types: translation unit, function, function declaration. model elements default is equivalent to an empty configuration.
  • name - Specifies the name of the artifact.
    • valueOf – Starts a valueOf condition where you can use the following conditions:
      • elementname – Access the name of an element.
      • elementtype – Access the element type of an element.
      • filename – Access the name of the containing file.
      • folderpath – Access the full qualified folder name.

Examples:

model elements default

model elements all

model elements Include, Macro, TypeDef


model elements default
name valueOf(elementname) +" ["+ valueOf(elementtype) +"]"

The above example shows, how to configure the name of the C/C++ artifacts. It consists of the element name concatenated with the element type in brackets. This is also the default name for C/C++ artifacts. The result is shown in the picture below.

If you want the artifact name to include the full path to the file that contains the artifact, you can combine folderpath and filename like in the following example:

name valueOf (folderpath) + valueOf (filename) + " - " + valueOf(elementname)

Caveat

Some names are not unique

The artifact names for CDT artifacts can’t be configured. itemis ANALYZE uses the name provided by CDT for each element. However, in some cases, this name is not unique. This is especially the case if two similar elements have the same name, for example if you have two C functions both named doSomething().

If ANALYZE detects such cases, it will append a count to the second and subsequent occurrences, e.g., doSomething and doSomething (1). However, if two functions have the same name but a different signature, like, e.g., void doSomething() and void doSomething(int param)), ANALYZE will not provide a distinct name for each of them. Both will appear as doSomething [Function], which may be confusing. Please note that this will only affect the way artifacts are displayed: ANALYZE will be able to properly distinguish them and to create links to each of them.

Non-unique names may also occur in some structured elements (struct, class, …) if there are parent elements with the same name. CDT should report them as errors, but ANALYZE can still handle them. In the following example the name of field a is not unique: 

struct Example { //Name is Example [Structure]
	int a; //Name is Example::a [Field]
	int b;
};

struct Example { //Name is Example (1) [Structure]
	int a; //Name is Example::a [Field]
	int b;
};
Some positions are not unique

Some (few) C elements may not be distinguishable from each other if they occur several times in the same file and have the same name. CDT provides an index to distinguish most elements occurring multiple times, but this is not the case for all elements. For example, two functions with the same signature can be distinguished, but two #include statements cannot. If two include statements import the same file, e.g., in two distinct #ifndef blocks, they will have the same name and position. ANALYZE will only create one artifact for both of them. This may cause side-effects in link management. For example, it might not be possible to delete a CDT Analyze link defined on the second occurrence of the #include statement from the ANALYZE Editor – you would have to delete such a link manually by removing the C comment. This should however be a rare case, as it only affects a few types of elements, #include being the only one that is known at this point.

To avoid this issue, it is recommended to avoid creating ANALYZE links to #include statements when using the CDT link type.

For example:

#ifdef A
//@link libA
#include "lib.h"
#endif

#ifdef B
//@link libB
#include "lib.h"
#endif

ANALYZE will find a single lib.h [Include] artifact, with two links to libA and libB, respectively. Creating a new link to lib.h [Include] will always add new C comments to the first #include occurrence, i.e., below @link libA. The ANALYZE Editor will not be able to delete the link to libB.

Version

An artifact’s version is used for suspicious links validation. Artifacts of this type do not provide a version.

itemis ANALYZE is able to recognize link information in C/C++ files, based on a portion of C or C++ code, like

/* @Req1234 */
void someOperation(Foo * param)

ANALYZE supports link maintenance both in the C/C++ code and by ANALYZE, i.e., on one hand the user can create/delete links by editing the C/C++ comments, on the other hand ANALYZE manipulates comments in the C/C++ code, as links are created/deleted in ANALYZE.

To configure the C/C++ access, the configuration of both a Eclipse CDT data access and at least one link type using this data access are required.

The actual configuration of how to find the comments and how to derive the linked artifacts' identifiers from these comments is done in the link type configuration.

The configuration covers:

  • … as block|line comment – Determines whether ANALYZE creates block or line comments for new links.
  • analyze comments of … – Which artifact type represents the C/C++ artifact. Possible values are A and B.
  • create links by … – This section specifies how ANALYZE calculates the content of new comments on link creation. The specification is a concatenation of static strings and values of artifact attributes.
  • locate links by – A regular expression for the text portion in comments in C/C++ files representing a link.
  • map { … } – As an option, it is possible to define link attributes and derive the attribute values similar to the identifier derivation specified by identified by.
  • where – Specifies which attributes are relevant for the identification of an artifact linked to a C/C++ element.
  • filtered elements – Specifies how to deal with link comments on filtered elements. Possible values are:
    • Delegate – Create a link from the first unfiltered parent element (or ignore if there is no matching parent). This is the default behavior.
    • Ignore – Always ignore link comments on filtered elements. No link will be created for such ignored comments.

In the where sections it is possible to add several rules to match groups in the regular expression specified by locate links by to attributes of the relevant artifacts. A rule is expressed by an equation of the form LeftHandSide = RightHandSide . The LeftHandSide is a concatenation of static strings and groups to the regular expression, the RightHandSide is a concatenation of static strings and values of artifact attributes and/or artifacts metadata identifier and resource. For a link, each of these expressions must match, i.e., they are linked by logical AND.

The above example shows a configuration for a data access of type Eclipse CDT. Given the comment /* @Req1234 */, ANALYZE creates a link from the C element holding the comment and Requirement Detail 1234.

ANALYZE assigns the value @Req1234, i.e., the whole match, to the wholeMarkup attribute. On link creation, ANALYZE concatenates @Req and the ID of the linked Requirement Detail, and then writes a block comment with this information.

Again, the example shows a configuration for a data access of type Eclipse CDT. Given a comment //@MYSHEET:A4, ANALYZE creates a link from the C element holding the comment to an artifact with attributes sheet="MYSHEET" and cell="A4". In this case, ANALYZE doesn’t populate any link attributes. On link creation, ANALYZE concatenates "@" + value of B.sheet + ":" + value of B.cell, and then creates a new line comment.

  • ANALYZE recognizes comments anywhere in a C/C++ file.
  • On one hand ANALYZE is able to find multiple matches in one comment, on the other hand ANALYZE creates a new comment for each new link. ANALYZE does not expand existing comments.
  • A new comment is always written in the line above the linked element.
  • ANALYZE recognizes the C/C++ elements visible in Eclipse’s outline view, i.e., files (translation units), operations, includes, macros, etc. ANALYZE does not recognize any C elements within operations, e.g., statements.
  • Comments are assigned to C/C++ elements according to the following rules (by order of priority):
    • A sequence of comments (i.e., not separated by an empty line) at the very beginning of the file (i.e., not preceded by an empty line) belongs to the translation unit.
    • End-of-line comments belong to the last element on that line.
    • A sequence of comments directly preceding an element belong to that element. The comment must be either on the same line or on the previous line, i.e., there must be no empty line between the comment and the following C/C++ element.
    • A comment inside a function belongs to the function.
    • The comment belongs to the translation unit.
  • Comments are always mapped to exactly one element. If several rules match for the same comment, the first rule has a higher priority, according to the aforementioned order. If the comment is assigned to a filtered element, the result will depend on the configuration: The comment will be assigned to the first unfiltered parent of this element if the configuration is set to „delegate”. It will be ignored otherwise (i.e., no link will be created for this comment).
  • If a link is deleted by means of ANALYZE, ANALYZE removes the link information from the C/C++ comment. If the comment is empty or includes whitespace characters only after the deletion, ANALYZE deletes the whole comment. In case the line is empty, ANALYZE deletes the line.

The following example illustrates these recognition rules:

// @Req11 - assigned to TranslationUnit
/*
 * @Req12 - assigned to TranslationUnit
 */

// @Req13 - assigned to TranslationUnit

// @Req15 - assigned to include 
/* @Req16 - assigned to include */
// If 'include' elements are filtered, these comments will be assigned to TranslationUnit instead. 
// If 'include' elements are filtered, and comments of filtered elements are ignored, these comments won't be assigned to any element. 
#include "stdafx.h"

// @Req17 - assigned to TranslationUnit

/**
 * @Req19 @Req20 - both assigned to operation _main
 */
// @Req22 @Req23 - both assigned to operation _main
int _tmain(int argc, int* argv[])
{
    return 0;
}
int _tmain2(int argc, int* argv[])
{
    //@Req28 - assigned to  _tmain2
    return 0;
    //@Req29 - assigned to  _tmain2
}

struct S1 { //@Req30 assigned to S1
    field a; //@Req31 assigned to S1::a
}

//@Req32 assigned to a
int a, /* @Req33 assigned to b */ b, c; //@Req33 assigned to c

Links of this link type will never become suspicious.

Eclipse editor drag-and-drop linking functionality

ANALYZE supports the creation of links by dragging elements from various ANALYZE views and dropping them into a C editor.

This functionality requires the following:

  • A unique link type needs to be configured between the artifact type of the elements being dragged to the C editor and the artifact type of target elements in the C editor.
  • There must be only one mapping of type „C” for this link type. Additionally, this mapping needs to support the creation of links by insertion of comments in C files.

If these conditions are fulfilled, a link can be created by dragging an element and dropping it into the C editor. A comment is inserted at the beginning of the line where the drop is performed, the source code being edited in the C editor is saved to disk, and a link is created automatically. If one of the conditions required for this functionality is not fulfilled, dropping is prevented and a message is shown that indicates the reason.

Codebeamer Eclipse Java (JDT)