documentation/html/development/forte_codequality.html - gerrit/www.eclipse.org/4diac - Git at Google

 <!DOCTYPE html>
 <!--
  Copyright (c) 2015, 2017 fortiss GmbH

  This program and the accompanying materials are made available under the
  terms of the Eclipse Public License 2.0 which is available at
  http://www.eclipse.org/legal/epl-2.0.

  SPDX-License-Identifier: EPL-2.0

  Contributors:
    Alois Zoitl, Jose Cabral
      - initial API and implementation and/or initial documentation
 -->

 <html lang="en">
 <head>
 	<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
 	<title>Assuring FORTE Code Quality</title>
 	<link rel="stylesheet" type="text/css" href="../help.css">
 </head>

 <body>

 <h1 id="topOfPage">Assuring FORTE Code Quality</h1>
 <p>Reducing the number of bugs and keep a high code quality is a constant struggle. For FORTE we apply several means and tools which we summarize here as we think they can be helpful for users planing to extend FORTE.</p>

 <h2 id="staticAnalysis">Static Code Analysis</h2>
 <p>Static code analyzers as the name implies perform an off-line analysis of your code and try to identify potential issues. For FORTE we are currently using the following two open source static code analyzers:</p>

 <ul>
 	<li><span class="inlineTitle">CPP Check</span>: is a tool you can directly use to check your code. However for Eclipse there also exists an Eclipse plugin you can install from the Eclipse market place.
 		Which makes its use much more convenient. CPP Check helps for example to find if correct pairs of new/delete are used or also on potential memory leaks.
 	</li>
 	<li><span class="inlineTitle">Clang's scan-build</span>: scan-build is a tool that comes with the C++ Compiler clang. It uses the clang compiler to perform the static analysis during compile time.
 		<p> To use it for checking FORTE you first need to change the C to clang's <span class="specificText">ccc-analyzer</span> and the C++ compiler to clang's <span class="specificText">c++-analyzer</span> during the CMake configuration of FORTE. Therefore it is recommended to use a separate build directory.</p>

 		<p>Furthermore instead of running </p>
 		<div class="code">make all</div>
 		<p>you need to invoke the comman.d</p>
 		<div class="code">scan-build -o ./static make</div>
 		<p>for building FORTE. The nice thing about scan-build is that it creates nice html files with explanations about the found problems.</p>

 	</li>
 </ul>

 <h2 id="dynamicAnalysis">Dynamic Analysis</h2>
 <p>Dynamic analysis tools help to find issues during the runtime. Typical issues are memory issues like memory leaks, out of bound access, stack over/underflows, or the use after memory is freed.</p>

 <ul>
 	<li><span class="inlineTitle">Valgrind</span>: Valgrind is definitely the most commonly known dynamic checker. It checks mainly for memory issues. Currently it is only available for Linux and there only for Intel platforms. The main drawback of Valgrind is that it tremendously slows down the execution of the application under test.
 	</li>
 	<li><span class="inlineTitle">Sanitizers</span>: Sanitizers are means for runtime checking that the complier adds to your application. They can be activated with compiler switches and have the great advantage that they are currently much faster than Valgrind. However they are only available for Clang and gcc. For the latter only partially. Currently we have worked with the following sanitizers

 	<ul>
 		<li>Address: Checks for memory and heap issues. Can be activated by adding
 			<div class="code">-fsanitize=address</div>
 			to the CMake option CMAKE_CXX_FLAGS.
 		</li>
 		<li>Undefined Behavior: Checks for undefined behavior in your code (e.g, overflows, div by zero). Can be activated by adding
 			<div class="code">-fsanitize=undefined</div>
 			to the CMake option CMAKE_CXX_FLAGS.
 		</li>
 		<li>Thread: To be tested</li>
 	</ul>
 </ul>

 <!-- ******************************* -->
 <h2 id="unitTests">Unit Tests</h2>
 <p>We applied the unit test framework provided by the Boost-library called Boost Test. You can find the current set of available unit test in the directory test. New unit tests are always more then welcome.</p>

 <h3>Install Boost Test</h3>
 To use execute unit tests at least <a href="http://www.boost.org/">boost 1.59</a> is needed.
 Download it and unzip it.

 <h4>under Linux</h4>
 <div class="code">wget -O boost_1_63_0.tar.gz http://sourceforge.net/projects/boost/files/boost/1.63.0/boost_1_63_0.tar.gz/download
 tar -xzvf boost_1_63_0.tar.gz
 cd boost_1_63_0/
 ./bootstrap.sh gcc
 sudo ./b2 install --prefix=installation/path toolset=gcc</div>

 <h4>under Windows</h4>
 For detailed instructions on installation under Windows have a look at this <a href="https://andres.jaimes.net/718/how-to-install-the-c-boost-libraries-on-windows/">Blog</a>.
 Otherwise follow this summary for cygwin:

 <ol>
 	<li>open a cygwin command line and go to your unziped folder</li>
 	<li>Start bootstrap.bat and specify your toolset.
 	Supported toolsets are: borland, como, gcc, gcc-nocygwin, intel-win32, metrowerks, mingw, msvc, vc7, vc8, vc9, vc10, vc11.
 	Use the following command for cygwin
 	<div class="code">./bootstrap.sh gcc</div></li>
 	<li>define an installation directory and specify a toolset.
 	Toolsets here are a little bit different from the ones we used before.
 	The following command creates two folders, include and lib.
 	Both folders should contain files afterwards, which takes a lot of time.
 	<div class="code">./b2 install --prefix=c:/installation/path toolset=gcc</div></li>
 </ol>

 <h3>Set CMake of the 4diac-rte</h3>
 Set the following configuration in CMake:

 <div class="code">FORTE_TESTS=ON
 FORTE_TESTS_INC_DIRS=path to generated include files have to be set under windows
 FORTE_TESTS_LINK_DIRS=path to generated libraries have to be set under windows</div>

 <p>The make target "all" generates a fortetest executable which executes all Tests.
 In case you want code coverage results also check FORTE_TEST_CODE_COVERAGE_ANALYSIS and create a make target in eclipse called TestCoverage the make target TestCoverage generates a folder with html files containing the coverage results.
 In case an error occures, uncomment</p>

 <div class="code">line 133: #ADD_DEFINITIONS (-fsanitize=address)
 line 166: remove -fsanitize=address</div>

 <h3>Function Block Tests</h3>
 <p>Based on Boost Test we developed a helper class which allows you to write unit test for Function Blocks in C++.
 For examples how to use it have a look on the test cases in the test/stdfblib directory.
 Write positive and negative test cases for your unit tests.</p>

 <h1>Where to go from here?</h1>

 <p>Go back to Development index:</p>

 <p><a href="../../html/development/developmentIndex.html">Development Index</a></p>

 <p>If you want to go back to the Start Here page, we leave you here a fast access</p>

 <p><a href="../../html/startHere/startHere.html">Start Here page</a></p>

 <p class="goToTop">Or <a href="#topOfPage">Go to top</a></p>

 </body>
 </html>
	<!DOCTYPE html>
	<!--
	Copyright (c) 2015, 2017 fortiss GmbH

	This program and the accompanying materials are made available under the
	terms of the Eclipse Public License 2.0 which is available at
	http://www.eclipse.org/legal/epl-2.0.

	SPDX-License-Identifier: EPL-2.0

	Contributors:
	Alois Zoitl, Jose Cabral
	- initial API and implementation and/or initial documentation
	-->

	<html lang="en">
	<head>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
	<title>Assuring FORTE Code Quality</title>
	<link rel="stylesheet" type="text/css" href="../help.css">
	</head>

	<body>

	<h1 id="topOfPage">Assuring FORTE Code Quality</h1>
	<p>Reducing the number of bugs and keep a high code quality is a constant struggle. For FORTE we apply several means and tools which we summarize here as we think they can be helpful for users planing to extend FORTE.</p>

	<h2 id="staticAnalysis">Static Code Analysis</h2>
	<p>Static code analyzers as the name implies perform an off-line analysis of your code and try to identify potential issues. For FORTE we are currently using the following two open source static code analyzers:</p>

	<ul>
	<li><span class="inlineTitle">CPP Check</span>: is a tool you can directly use to check your code. However for Eclipse there also exists an Eclipse plugin you can install from the Eclipse market place.
	Which makes its use much more convenient. CPP Check helps for example to find if correct pairs of new/delete are used or also on potential memory leaks.
	</li>
	<li><span class="inlineTitle">Clang's scan-build</span>: scan-build is a tool that comes with the C++ Compiler clang. It uses the clang compiler to perform the static analysis during compile time.
	<p> To use it for checking FORTE you first need to change the C to clang's <span class="specificText">ccc-analyzer</span> and the C++ compiler to clang's <span class="specificText">c++-analyzer</span> during the CMake configuration of FORTE. Therefore it is recommended to use a separate build directory.</p>

	<p>Furthermore instead of running </p>
	<div class="code">make all</div>
	<p>you need to invoke the comman.d</p>
	<div class="code">scan-build -o ./static make</div>
	<p>for building FORTE. The nice thing about scan-build is that it creates nice html files with explanations about the found problems.</p>

	</li>
	</ul>

	<h2 id="dynamicAnalysis">Dynamic Analysis</h2>
	<p>Dynamic analysis tools help to find issues during the runtime. Typical issues are memory issues like memory leaks, out of bound access, stack over/underflows, or the use after memory is freed.</p>

	<ul>
	<li><span class="inlineTitle">Valgrind</span>: Valgrind is definitely the most commonly known dynamic checker. It checks mainly for memory issues. Currently it is only available for Linux and there only for Intel platforms. The main drawback of Valgrind is that it tremendously slows down the execution of the application under test.
	</li>
	<li><span class="inlineTitle">Sanitizers</span>: Sanitizers are means for runtime checking that the complier adds to your application. They can be activated with compiler switches and have the great advantage that they are currently much faster than Valgrind. However they are only available for Clang and gcc. For the latter only partially. Currently we have worked with the following sanitizers

	<ul>
	<li>Address: Checks for memory and heap issues. Can be activated by adding
	<div class="code">-fsanitize=address</div>
	to the CMake option CMAKE_CXX_FLAGS.
	</li>
	<li>Undefined Behavior: Checks for undefined behavior in your code (e.g, overflows, div by zero). Can be activated by adding
	<div class="code">-fsanitize=undefined</div>
	to the CMake option CMAKE_CXX_FLAGS.
	</li>
	<li>Thread: To be tested</li>
	</ul>
	</ul>

	<!-- ******************************* -->
	<h2 id="unitTests">Unit Tests</h2>
	<p>We applied the unit test framework provided by the Boost-library called Boost Test. You can find the current set of available unit test in the directory test. New unit tests are always more then welcome.</p>

	<h3>Install Boost Test</h3>
	To use execute unit tests at least <a href="http://www.boost.org/">boost 1.59</a> is needed.
	Download it and unzip it.

	<h4>under Linux</h4>
	<div class="code">wget -O boost_1_63_0.tar.gz http://sourceforge.net/projects/boost/files/boost/1.63.0/boost_1_63_0.tar.gz/download
	tar -xzvf boost_1_63_0.tar.gz
	cd boost_1_63_0/
	./bootstrap.sh gcc
	sudo ./b2 install --prefix=installation/path toolset=gcc</div>

	<h4>under Windows</h4>
	For detailed instructions on installation under Windows have a look at this <a href="https://andres.jaimes.net/718/how-to-install-the-c-boost-libraries-on-windows/">Blog</a>.
	Otherwise follow this summary for cygwin:

	<ol>
	<li>open a cygwin command line and go to your unziped folder</li>
	<li>Start bootstrap.bat and specify your toolset.
	Supported toolsets are: borland, como, gcc, gcc-nocygwin, intel-win32, metrowerks, mingw, msvc, vc7, vc8, vc9, vc10, vc11.
	Use the following command for cygwin
	<div class="code">./bootstrap.sh gcc</div></li>
	<li>define an installation directory and specify a toolset.
	Toolsets here are a little bit different from the ones we used before.
	The following command creates two folders, include and lib.
	Both folders should contain files afterwards, which takes a lot of time.
	<div class="code">./b2 install --prefix=c:/installation/path toolset=gcc</div></li>
	</ol>

	<h3>Set CMake of the 4diac-rte</h3>
	Set the following configuration in CMake:

	<div class="code">FORTE_TESTS=ON
	FORTE_TESTS_INC_DIRS=path to generated include files have to be set under windows
	FORTE_TESTS_LINK_DIRS=path to generated libraries have to be set under windows</div>

	<p>The make target "all" generates a fortetest executable which executes all Tests.
	In case you want code coverage results also check FORTE_TEST_CODE_COVERAGE_ANALYSIS and create a make target in eclipse called TestCoverage the make target TestCoverage generates a folder with html files containing the coverage results.
	In case an error occures, uncomment</p>

	<div class="code">line 133: #ADD_DEFINITIONS (-fsanitize=address)
	line 166: remove -fsanitize=address</div>

	<h3>Function Block Tests</h3>
	<p>Based on Boost Test we developed a helper class which allows you to write unit test for Function Blocks in C++.
	For examples how to use it have a look on the test cases in the test/stdfblib directory.
	Write positive and negative test cases for your unit tests.</p>

	<h1>Where to go from here?</h1>

	<p>Go back to Development index:</p>

	<p><a href="../../html/development/developmentIndex.html">Development Index</a></p>

	<p>If you want to go back to the Start Here page, we leave you here a fast access</p>

	<p><a href="../../html/startHere/startHere.html">Start Here page</a></p>

	<p class="goToTop">Or <a href="#topOfPage">Go to top</a></p>

	</body>
	</html>