Qt Creator DevIntro CppSupport: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
No edit summary
(Cleanup)
 
(6 intermediate revisions by one other user not shown)
Line 1: Line 1:
[[Category:Tools::QtCreator]]
[[Category:Tools::QtCreator]]
[toc align_right="yes" depth="3"]


<BIG RED>CAUTION: This page is no yet reviewed by the C++ Support maintainer.</BIG RED>
<BIG style="color:red">CAUTION: This page is no yet reviewed by the C++ Support maintainer.</BIG>


= C++ Support in Qt Creator =
= C++ Support in Qt Creator =
Line 8: Line 7:
This page is meant as an introduction / collection of hints for developers wanting to help with the C++ Support in Qt Creator.
This page is meant as an introduction / collection of hints for developers wanting to help with the C++ Support in Qt Creator.


Here is a filter showing all unresolved C++ bugs: "Creator / C++ > All unresolved bugs":https://bugreports.qt.io/secure/IssueNavigator.jspa?mode=hide&amp;amp;requestId=13573
Here is a filter showing all unresolved C++ bugs: [https://bugreports.qt.io/secure/IssueNavigator.jspa?mode=hide&requestId=13573 Creator / C++ > All unresolved bugs]


Please read the mailing list post "Editors/Code-models: new year's resolutions":http://lists.qt.io/pipermail/qt-creator/2013-January/001768.html .
Please read the mailing list post [http://lists.qt-project.org/pipermail/qt-creator/2013-January/001768.html Editors/Code-models: new year's resolutions] .


Hint: The paths on this page are relative to the top level directory of Qt Creator.
Hint: The paths on this page are relative to the top level directory of Qt Creator.
Line 61: Line 60:




h2. Tools used for development
== Tools used for development ==
 
There is a number of tools you can and should make use of. They should work on all major platforms (GNU/Linux, Mac, Windows).
There is a number of tools you can and should make use of. They should work on all major platforms (GNU/Linux, Mac, Windows).


Line 70: Line 68:
* cplusplus-frontend - Parses given files (parser as standalone tool).
* cplusplus-frontend - Parses given files (parser as standalone tool).


h3. cplusplus-mkvisitor
=== cplusplus-mkvisitor ===
 
Source directory: src/tools/cplusplus-mkvisitor
Source directory: src/tools/cplusplus-mkvisitor


Usage &amp; Purpose:
Usage & Purpose:
<code>$ ./cplusplus-mkvisitor -h
<code>$ ./cplusplus-mkvisitor -h
Usage: cplusplus-mkvisitor [-v] [path to AST.h]
Usage: cplusplus-mkvisitor [-v] [path to AST.h]
Line 86: Line 83:
<code>$ ./cplusplus-mkvisitor > myvisitor.cpp<code>
<code>$ ./cplusplus-mkvisitor > myvisitor.cpp<code>


h3. cplusplus-update-frontend
=== cplusplus-update-frontend ===
 
Source directory: src/tools/cplusplus-update-frontend
Source directory: src/tools/cplusplus-update-frontend


Usage &amp; Purpose:
Usage & Purpose:
</code>$ ./cplusplus-update-frontend -h
</code>$ ./cplusplus-update-frontend -h
Usage: cplusplus-update-frontend
Usage: cplusplus-update-frontend
Line 121: Line 117:
Source directory: tests/tools/cplusplus-ast2png
Source directory: tests/tools/cplusplus-ast2png


Usage &amp; Purpose:
Usage & Purpose:
</code>$ ./cplusplus-ast2png -h
</code>$ ./cplusplus-ast2png -h
Usage: cplusplus-ast2png [-v] [-p ast] <file1> <file2> …
Usage: cplusplus-ast2png [-v] [-p ast] <file1> <file2> …
Line 143: Line 139:
you might want to execute:
you might want to execute:


$ echo "int foo() {}" | ./cplusplus-ast2png &amp;&amp; xdg-open _stdincontents.cpp.ast.png
$ echo "int foo() {}" | ./cplusplus-ast2png && xdg-open _stdincontents.cpp.ast.png


Prerequisites:
Prerequisites:
Line 149: Line 145:
  2) Make sure to have an up to date dumpers file by using 'cplusplus-update-frontend'.<code>
  2) Make sure to have an up to date dumpers file by using 'cplusplus-update-frontend'.<code>


<code>dot</code> comes with "graphviz":http://www.graphviz.org/. On Ubuntu you have to install the package graphviz.
<code>dot</code> comes with [http://www.graphviz.org/ graphviz]. On Ubuntu you have to install the package graphviz.


Note also that processing might fail for too big input files. Generating an image (dot) is a cpu and memory intensive task. This tool is meant for small snippets, therefore the processing of input from stdin.
Note also that processing might fail for too big input files. Generating an image (dot) is a cpu and memory intensive task. This tool is meant for small snippets, therefore the processing of input from stdin.
Line 165: Line 161:
Source directory: tests/manual/cplusplus-frontend
Source directory: tests/manual/cplusplus-frontend


Usage &amp; Purpose:
Usage & Purpose:
</code>$ ./cplusplus-frontend -h
</code>$ ./cplusplus-frontend -h
Usage: cplusplus-frontend [-v] <file1> <file2> …
Usage: cplusplus-frontend [-v] <file1> <file2> …
Line 199: Line 195:
==== Running all tests ====
==== Running all tests ====


# (Open &amp;) Build the project tests/auto/cplusplus.pro either in-source or as shadow-build.
# (Open &) Build the project tests/auto/cplusplus.pro either in-source or as shadow-build.
# Run <code>$ make check</code> to run all tests. If a test fails, subsequent tests will not be executed, therefore you might want to add "-i" to the command for ignoring failures. If you run the tests from Qt Creator, you probably want to add a custom run configuration calling these commands.
# Run <code>$ make check</code> to run all tests. If a test fails, subsequent tests will not be executed, therefore you might want to add "-i" to the command for ignoring failures. If you run the tests from Qt Creator, you probably want to add a custom run configuration calling these commands.


=== Manual tests ===
=== Manual tests ===

Latest revision as of 14:21, 24 May 2015


CAUTION: This page is no yet reviewed by the C++ Support maintainer.

C++ Support in Qt Creator

This page is meant as an introduction / collection of hints for developers wanting to help with the C++ Support in Qt Creator.

Here is a filter showing all unresolved C++ bugs: Creator / C++ > All unresolved bugs

Please read the mailing list post Editors/Code-models: new year's resolutions .

Hint: The paths on this page are relative to the top level directory of Qt Creator.

Related source directories and classes

The sources for the C++ Support are spread over several directories. To give you a quick overview, here are some important source directories and prominent classes you will find in them.

Libraries

  • src/libs/3rdparty/cplusplus - C++ Frontend
Token, Lexer, Parser, Bind, Control, AST, ASTVisitor, Scope, Type, TranslationUnit
  • src/libs/cplusplus
Preprocessor, Snapshot, LookupContext, Document, Macro, FindUsages

Plugins

  • src/plugins/cppeditor - C++ Editor
CppPlugin, CppClass, CppFunction, CppInclude, SemanticHighlighter
  • src/plugins/cpptools - C++ Tools
CppToolsPlugin, FindInClass, FindLocalSymbols, FindFunctionDefinition, IndexingSupport, CheckSymbols, CppCompletionAssistProvider, CppPreprocessor, CppModelManager, CppLocatorFilter, SemanticInfo

General hints

  • Care about the tests - See also section about tests below.

You can learn a lot from tests. Please run them. Please fix them. Please add new tests for new functionality.

  • Debugging / Remove optimization before debugging

src/libs/cplusplus/cplusplus.pro: Comment out

QMAKE_CXXFLAGS_DEBUG ''= -O2

for proper debugging.

  • Debugging / Enable parser tracing

src/libs/3rdparty/cplusplus/Parser.cpp: Comment out

#define CPLUSPLUS_NO_DEBUG_RULE

to get output like:

- parseTranslationUnit, ahead: '' (1) - block-errors: 0
- parseTranslationUnit, ahead: 'typedef' (1) - block-errors: 0
 parseDeclaration, ahead: 'typedef' (1) - block-errors: 0
 parseSimpleDeclaration, ahead: 'typedef' (1) - block-errors: 0
- parseBuiltinTypeSpecifier, ahead: 'long' (2) - block-errors: 0
- parseBuiltinTypeSpecifier, ahead: 'int' (3) - block-errors: 0

  • Debugging / Enable preprocessor tracing

Set the environment variable

QTCREATOR_DUMP_FILENAME_WHILE_PARSING

(evaluated at run time) to get output like:


Parsing file: "/usr/include/stdlib.h"
Parsing file: "/usr/include/c/4.6/new"
Parsing file: "/usr/lib/gcc/x86_64-linux-gn
  • Debugging / Enable dumping the ModelManager configuration

Set the environment variable

QTCREATOR_DUMP_PROJECT_INFO

(evaluated at run time) to get debug statements regarding the detected language, C11 detection, Qt Version, precompiled header, defines, includes, frameworkPaths, sources. The merged include paths, merged framework paths and merged defined macros will also be printed. In total you will get quite much output. This configuration changes on e.g. switching Kits.

  • Use the provided tools - See also section about tools below.


Tools used for development

There is a number of tools you can and should make use of. They should work on all major platforms (GNU/Linux, Mac, Windows).

  • cplusplus-mkvisitor - Creates an AST visitor class.
  • cplusplus-update-frontend - Updates sources in the parser after modifying AST.h.
  • cplusplus-ast2png - Visualizes AST and symbol hierarchy by generating PNG files for given code.
  • cplusplus-frontend - Parses given files (parser as standalone tool).

cplusplus-mkvisitor

Source directory: src/tools/cplusplus-mkvisitor

Usage & Purpose:

$ ./cplusplus-mkvisitor -h
Usage: cplusplus-mkvisitor [-v] [path to AST.h]

Print a visitor class based on AST.h to stdout.

Default path: $QTC_SOURCE/src/libs/3rdparty/cplusplus/AST.h.

Example Usage:

$ ./cplusplus-mkvisitor > myvisitor.cpp<code>

=== cplusplus-update-frontend ===
Source directory: src/tools/cplusplus-update-frontend

Usage & Purpose:

$ ./cplusplus-update-frontend -h

Usage: cplusplus-update-frontend

cplusplus-update-frontend <frontend-dir> <dumpers-file>

Generate appropriate header and source files of the C+ frontend accordingly to AST.h and print the paths of the written files. Run this tool after modifying AST.h.

Default values:

frontend-dir: $QTC_SOURCE/src/libs/3rdparty/cplusplus

dumpers-file: $QTC_SOURCE/tests/tools/cplusplus-ast2png/dumpers.inc

Example Usage:

$ ./cplusplus-update-frontend

$QTC_SOURCE/src/libs/3rdparty/cplusplus/AST.h $QTC_SOURCE/src/libs/3rdparty/cplusplus/ASTVisit.cpp $QTC_SOURCE/src/libs/3rdparty/cplusplus/ASTMatch0.cpp $QTC_SOURCE/src/libs/3rdparty/cplusplus/ASTMatcher.cpp $QTC_SOURCE/src/libs/3rdparty/cplusplus/ASTClone.cpp $QTC_SOURCE/src/libs/3rdparty/cplusplus/AST.cpp $QTC_SOURCE/src/libs/3rdparty/cplusplus/ASTVisitor.h $QTC_SOURCE/src/libs/3rdparty/cplusplus/ASTMatcher.h $QTC_SOURCE/tests/tools/cplusplus-ast2png/dumpers.inc $QTC_SOURCE/src/libs/3rdparty/cplusplus/ASTfwd.h

$QTC_SOURCE/src/libs/3rdparty/cplusplus/ASTPatternBuilder.h

=== cplusplus-ast2png ===

Source directory: tests/tools/cplusplus-ast2png

Usage & Purpose:

$ ./cplusplus-ast2png -h

Usage: cplusplus-ast2png [-v] [-p ast] <file1> <file2> …

Visualize AST and symbol hierarchy of given C++ files by generating png image files in the same directory as the input files. Print paths to generated image files.

Options:

-v Run with increased verbosity.
-p <ast> Parse each file as <ast>. <ast> is one of:

- 'declarator' or 'dr'

- 'expression' or 'ex'
- 'declaration' or 'dn'
- 'statement' or 'st'
- 'translationunit' or 'tr'
If this option is not provided, each file is tried to be parsed as
declarator, expression, etc. using the stated order.

Standard input is also read. The resulting files start with "_stdincontents.cpp" and are created in the current working directory. To show the AST for simple snippets you might want to execute:

$ echo "int foo() {}" | ./cplusplus-ast2png && xdg-open _stdincontents.cpp.ast.png

Prerequisites:

1) Make sure to have 'dot' from graphviz locatable by PATH.

2) Make sure to have an up to date dumpers file by using 'cplusplus-update-frontend'.

<code>dot

comes with graphviz. On Ubuntu you have to install the package graphviz.

Note also that processing might fail for too big input files. Generating an image (dot) is a cpu and memory intensive task. This tool is meant for small snippets, therefore the processing of input from stdin.

Example Usage: $ echo "int foo() {}" | ./cplusplus-ast2png _stdincontents.cpp.ast.png _stdincontents.cpp.symbols.png $ ./cplusplus-ast2png /tmp/helloworld.cpp /tmp/helloworld.cpp.ast.png

/tmp/helloworld.cpp.symbols.png

=== cplusplus-frontend ===

Source directory: tests/manual/cplusplus-frontend

Usage & Purpose:

$ ./cplusplus-frontend -h

Usage: cplusplus-frontend [-v] <file1> <file2> …

Run the parser with the given files.

Example Usage:

$ ./cplusplus-frontend tests/t1.cpp

tests/t1.cpp:37: error: expected a declaration

typedef enum { k };

^

== Tests ==

=== "Plugin" auto tests ===

These tests are in src/plugins/cpptools/*_test.cpp and src/plugins/cppeditor/*_test.cpp. They are included in the plugin itself, since they can't be separated easily.

Make sure that WITH_TESTS is defined (currently this is set for a debug build). Otherwise Qt Creator will not understand the "-test" option.

Run the tests with: <code>$ ./qtcreator -test CppTools -test CppEditor

Qt Creator will start, execute all tests and quit. Watch the output.

"External" auto tests

You can find these tests in tests/auto/cplusplus. They are the 'separable' tests.

Just build and run the relevant test project.

If you're using shadow builds, make sure to place the build directory accordingly to the source tree inside the build directory of Qt Creator since the tests referene libCPlusPlus.so.1 from Qt Creator. If you run the tests from Qt Creator, you probably want to add the Qt Creator project as a dependency (Projects, <test project>, Dependencies).

Running all tests

  1. (Open &) Build the project tests/auto/cplusplus.pro either in-source or as shadow-build.
  2. Run
    $ make check
    
    to run all tests. If a test fails, subsequent tests will not be executed, therefore you might want to add "-i" to the command for ignoring failures. If you run the tests from Qt Creator, you probably want to add a custom run configuration calling these commands.

Manual tests