Projects/Edu/KStars/C++ developer tools with KStars on Linux: Difference between revisions

    From KDE TechBase
    < Projects‎ | Edu‎ | KStars
    No edit summary
     
    (13 intermediate revisions by the same user not shown)
    Line 1: Line 1:
    This page describes how to use open-source C++ tools to hunt down memory errors and improve the code quality.
    This page describes how to use open-source C++ tools to hunt down memory errors and improve the code quality.
    == Reduce compilation time ==


    === CCache ===
    === CCache ===
    Line 16: Line 18:


    You can build KStars after these steps normally, CMake will put the compiler invocation after the ccache command and the object files will be saved to the local cache when a make command is executed.
    You can build KStars after these steps normally, CMake will put the compiler invocation after the ccache command and the object files will be saved to the local cache when a make command is executed.
    === Unity Build ===
    Unity Build is a build technique to include the existing C++ files into temporary super C++ files and build these super files with the compiler instead of the original. The advantage of this method is that the compiler is invoked less times and the build time can be reduced dramatically.
    In the KStars build system, a cmake flag (-DUNITY_BUILD=ON) is needed to enable this support. For example:
      cmake . -DUNITY_BUILD=ON
    To get an idea about the speed-up: the KStars build was cut to 8 min from 21 min on my older laptop.
    == Code formatting tools ==


    === Clang Format ===
    === Clang Format ===
    Line 26: Line 40:


    The current bleeding-edge Clang Format does not support value indentation (style option: AlignConsecutiveMacros) after #define as of now (June 2017), therefore, a patched package is uploaded to this wiki page which contains the "define patch" from https://reviews.llvm.org/D28462. Unfortunately, the package file is zipped because this wiki does not support to upload .deb files directly: [[File:Clang-format-package.zip]].
    The current bleeding-edge Clang Format does not support value indentation (style option: AlignConsecutiveMacros) after #define as of now (June 2017), therefore, a patched package is uploaded to this wiki page which contains the "define patch" from https://reviews.llvm.org/D28462. Unfortunately, the package file is zipped because this wiki does not support to upload .deb files directly: [[File:Clang-format-package.zip]].
    If somebody uses an unpatched Clang 5.0 version then he must remove the 'AlignConsecutiveMacros" from the .clang-format file and commit only the formatted files instead of reformatting the whole codebase.


    When clang-format is installed, a cmake flag (-DFORMAT_CODE=ON) is needed to enable Clang Format support. For example:
    When clang-format is installed, a cmake flag (-DFORMAT_CODE=ON) is needed to enable Clang Format support. For example:
    Line 34: Line 50:


       make clang-format
       make clang-format
    Individual files can be also formatted. An example command:
      clang-format-5.0 -style=file -i Tests/auxiliary/testcachingdms.cpp
    == Memory error checkers ==


    === Sanitizers with Clang ===
    === Sanitizers with Clang ===


    Official homepages:
    Official homepages:
    * https://clang.llvm.org/docs/AddressSanitizer.html
    * https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html


    https://clang.llvm.org/docs/AddressSanitizer.html
    https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html


    The two most useful Clang sanitizers are useful to detect memory handling errors (ASan) or undefined behaviors (UBSan). The application/library must be recompiled with special compiler flags to have an instrumented binary. The checks are performed during runtime with minimal slowdown.
    The two most useful Clang sanitizers are useful to detect memory handling errors (ASan) or undefined behaviors (UBSan). The application/library must be recompiled with special compiler flags to have an instrumented binary. The checks are performed during runtime with minimal slowdown.
    Line 59: Line 80:


    Other sanitizers:
    Other sanitizers:
    * MemorySanitizer: basically, a subset of AddressSanitizer checks.
    * Control Flow Sanitizer: big slowdown in compilation time+runtime, but it will detect mostly the same errors like UBSan.
    === Valgrind ===
    Official homepage: http://valgrind.org/
    Valgrind is a memory error checker. There is a suppression file in the repository at tools/valgrind.supp. To start KStars with valgrind, go to the root of the git repository and run this example command:
      valgrind --leak-check=full --show-reachable=yes --track-origins=yes --gen-suppressions=all --suppressions=tools/valgrind.supp kstars
    == Static code analyzers ==
    === cppcheck ===
    Official homepage: http://cppcheck.sourceforge.net/
    cppcheck is a static code analyzer for C++. There is a script in the Git repository to run cppcheck over the codebase:
      tools/run_cppcheck.sh
    === Clazy ===
    Official homepage: https://github.com/KDE/clazy
    Clazy is a Qt-oriented static code analyzer for C++ based on Clang. There is a script in the Git repository to run this tool over the codebase:
      tools/run_clazy_static_code_analysis.sh
    It is recommended to install the Clazy built for Clang 3.9 on Ubuntu Xenial (clazy39 package from this PPA: [https://launchpad.net/~csaba-kertesz/+archive/ubuntu/random]).
    === Clang Static Analyzer ===
    Official homepage: https://clang-analyzer.llvm.org/
    Clang Static Analyzer is a Clang-based static code analyzer for C++. There is a script in the Git repository to run this tool over the codebase:
      tools/run_clang_static_code_analyser.sh
    The script uses Clang 4.0 for the analysis.
    === Krazy ===
    Official homepage: https://community.kde.org/Guidelines_and_HOWTOs/Code_Checking#The_KDE_.27Krazy.27_Checker
    A static code analyzer from KDE. There is a script in the Git repository to run this tool over the codebase:
      tools/run_krazy.sh
    krazy package can be install to Ubuntu from this PPA: [https://launchpad.net/~csaba-kertesz/+archive/ubuntu/random].
    === Coverity ===
    Official homepage: http://www.coverity.com/
    Coverity is a commercial C++ static code analyzer from Synopsys, but it is free for open-source projects. There is a script in the Git repository to run this tool over the codebase and upload the result:
      tools/run_krazy.sh


    - MemorySanitizer: basically, a subset of AddressSanitizer checks.
    However, a build tool must be downloaded from their website, a contributor must be registered and the project must be added. During GSoC 2017, I did so and the analysis results are shown here: https://scan.coverity.com/projects/kstars_kde
    - Control Flow Sanitizer: big slowdown in compilation time+runtime, but it will detect mostly the same errors like UBSan.

    Latest revision as of 11:07, 30 October 2017

    This page describes how to use open-source C++ tools to hunt down memory errors and improve the code quality.

    Reduce compilation time

    CCache

    Official homepage: https://ccache.samba.org

    CCache is a useful tool to cache the compiled object files to avoid recompilation of the same source files. A typical use case is changing git branches when some include files are modified. By default, the compiler would recompile the affected source files after each branch checkout. With CCache, the build system can get the already-compiled object file from a local cache on the disk if available.

    Install CCache on Ubuntu Linux:

      sudo apt-get install ccache
    

    Add the -DCCACHE_SUPPORT=ON to the CMake flags to enable this feature. For example:

      cmake . -DCCACHE_SUPPORT=ON
    

    You can build KStars after these steps normally, CMake will put the compiler invocation after the ccache command and the object files will be saved to the local cache when a make command is executed.

    Unity Build

    Unity Build is a build technique to include the existing C++ files into temporary super C++ files and build these super files with the compiler instead of the original. The advantage of this method is that the compiler is invoked less times and the build time can be reduced dramatically.

    In the KStars build system, a cmake flag (-DUNITY_BUILD=ON) is needed to enable this support. For example:

      cmake . -DUNITY_BUILD=ON
    

    To get an idea about the speed-up: the KStars build was cut to 8 min from 21 min on my older laptop.

    Code formatting tools

    Clang Format

    Official homepage: https://clang.llvm.org/docs/ClangFormat.html

    Clang Format can indent the source codes with a defined style. The config file (.clang-format) is in the root of the KStars Git repository. The clang format can be installed easily in Ubuntu Linux from the LLVM repositories (http://apt.llvm.org/):

      sudo apt-get install clang-format-5.0
    

    The current bleeding-edge Clang Format does not support value indentation (style option: AlignConsecutiveMacros) after #define as of now (June 2017), therefore, a patched package is uploaded to this wiki page which contains the "define patch" from https://reviews.llvm.org/D28462. Unfortunately, the package file is zipped because this wiki does not support to upload .deb files directly: File:Clang-format-package.zip.

    If somebody uses an unpatched Clang 5.0 version then he must remove the 'AlignConsecutiveMacros" from the .clang-format file and commit only the formatted files instead of reformatting the whole codebase.

    When clang-format is installed, a cmake flag (-DFORMAT_CODE=ON) is needed to enable Clang Format support. For example:

      cmake . -DFORMAT_CODE=ON
    

    To format the code, a make command must be executed:

      make clang-format
    

    Individual files can be also formatted. An example command:

      clang-format-5.0 -style=file -i Tests/auxiliary/testcachingdms.cpp
    

    Memory error checkers

    Sanitizers with Clang

    Official homepages:


    The two most useful Clang sanitizers are useful to detect memory handling errors (ASan) or undefined behaviors (UBSan). The application/library must be recompiled with special compiler flags to have an instrumented binary. The checks are performed during runtime with minimal slowdown.

    When Clang is installed and used to compile KStars under Linux or macOS, a cmake flag (-DCLANG_SANITIZERS=ON) is needed to enable this support. For example:

      cmake . -DCLANG_SANITIZERS=ON
    

    Export these environmental variables before running the recompiled KStars:

      export ASAN_OPTIONS=detect_odr_violation=0
      export UBSAN_OPTIONS=print_stacktrace=1
    

    The reasons for the above things: skip the odr checks which are not useful and print backtraces for the undefined behavior errors.

    To get demangled backtraces, at least on Ubuntu, a symlink (llvm-symbolizer) must be created from llvm-symbolizer-x.x because AddressSanitizer will call this binary without versioning in the executable name.

    Other sanitizers:

    • MemorySanitizer: basically, a subset of AddressSanitizer checks.
    • Control Flow Sanitizer: big slowdown in compilation time+runtime, but it will detect mostly the same errors like UBSan.

    Valgrind

    Official homepage: http://valgrind.org/

    Valgrind is a memory error checker. There is a suppression file in the repository at tools/valgrind.supp. To start KStars with valgrind, go to the root of the git repository and run this example command:

      valgrind --leak-check=full --show-reachable=yes --track-origins=yes --gen-suppressions=all --suppressions=tools/valgrind.supp kstars
    

    Static code analyzers

    cppcheck

    Official homepage: http://cppcheck.sourceforge.net/

    cppcheck is a static code analyzer for C++. There is a script in the Git repository to run cppcheck over the codebase:

      tools/run_cppcheck.sh
    

    Clazy

    Official homepage: https://github.com/KDE/clazy

    Clazy is a Qt-oriented static code analyzer for C++ based on Clang. There is a script in the Git repository to run this tool over the codebase:

      tools/run_clazy_static_code_analysis.sh
    

    It is recommended to install the Clazy built for Clang 3.9 on Ubuntu Xenial (clazy39 package from this PPA: [1]).

    Clang Static Analyzer

    Official homepage: https://clang-analyzer.llvm.org/

    Clang Static Analyzer is a Clang-based static code analyzer for C++. There is a script in the Git repository to run this tool over the codebase:

      tools/run_clang_static_code_analyser.sh
    

    The script uses Clang 4.0 for the analysis.

    Krazy

    Official homepage: https://community.kde.org/Guidelines_and_HOWTOs/Code_Checking#The_KDE_.27Krazy.27_Checker

    A static code analyzer from KDE. There is a script in the Git repository to run this tool over the codebase:

      tools/run_krazy.sh
    

    krazy package can be install to Ubuntu from this PPA: [2].

    Coverity

    Official homepage: http://www.coverity.com/

    Coverity is a commercial C++ static code analyzer from Synopsys, but it is free for open-source projects. There is a script in the Git repository to run this tool over the codebase and upload the result:

      tools/run_krazy.sh
    

    However, a build tool must be downloaded from their website, a contributor must be registered and the project must be added. During GSoC 2017, I did so and the analysis results are shown here: https://scan.coverity.com/projects/kstars_kde