--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/buildframework/helium/doc/src/manual/coverity.rst Fri Aug 13 14:59:05 2010 +0300
@@ -0,0 +1,237 @@
+.. index::
+ module: Coverity Prevent Tool
+
+========================
+Coverity Prevent Tool
+========================
+
+.. contents::
+
+This document describes requirements and how to run Coverity Prevent tool with sbs builds using Helium.
+
+Introduction
+-------------------------
+
+- Coverity Prevent analyzes source code to find defects early in the development cycle, reducing the risks associated with coding. Included with Prevent are workflow tools that track and manage defects from initial discovery through final resolution.
+- With high precision, Coverity Prevent analyzes source code and detects critical software defects in the following categories:
+
+ **Quality**
+ Coverity Prevent detects bugs at compile-time that can cause run-time crashes. For example: memory leaks, use-after-free errors, and illegal pointer accesses.
+
+ **Security**
+ Early during development, Coverity Prevent can detect the security vulnerabilities that hackers can exploit and help you eliminate serious problems, such as denial of service, data or memory corruption, and privilege escalation. Vulnerabilities detected can include buffer overruns, integer overflows, format string errors, and SQL injection attacks.
+
+ **Concurrency**
+ Coverity Prevent can detect errors in multi-threaded programs that, given the complexity of concurrent programming, can be extremely difficult to track down or reproduce. Detected defects include potential deadlocks or misuse of locks.
+
+Description
+-------------------------
+
+- Coverity Prevent tool is integrated with Helium to measure C++ code coverage.
+- Helium does measure C++ code coverage and gives output results in the format of HTML and errors could be submitted to remote database server.
+- Helium runs coverity prevet tool commands, in sequential using targets. Those targets are defined below..
+- Helium runs Coverity Prevent tool targets if ``coverity.enabled`` is set to ``true``
+- Coverity command can be run using the ``<hlm:coverity>`` task.
+- Coverity task will validate is the command passed to task is starts with ``cov-`` and then it will run the command.
+- Coverity command options can passed through the datatypes ``<hlm:coverityoptions>`` or ``<hlm:arg>``.
+- Below example shows how parameters can be passed to coverity command:
+
+.. code-block:: xml
+
+ <hlm:coverity command="cov-link" dir="${build.drive}/">
+ <hlm:arg name="--dir" value="${coverity.inter.dir}"/>
+ <hlm:arg name="--collect" value=""/>
+ <hlm:arg name="-of" value="${coverity.link.dir}/all.link"/>
+ </hlm:coverity>
+
+.. code-block:: xml
+
+ <hlm:coverityoptions id="coverity.analyze.options">
+ <hlm:arg name="--dir" value="${coverity.analyze.dir}"/>
+ <hlm:arg name="--all" value=""/>
+ <hlm:arg name="--symbian" value=""/>
+ <hlm:arg name="--append" value=""/>
+ <hlm:arg name="--enable-callgraph-metrics" value=""/>
+ </hlm:coverityoptions>
+
+ <hlm:coverity command="cov-analyze" dir="${build.drive}/">
+ <hlm:coverityoptions refid="coverity.analyze.options"/>
+ </hlm:coverity>
+
+Helium Targets
+--------------------------
+
+Coverity configure
+::::::::::::::::::::::::
+
+ The ``cov-configure`` command configures a compiler or family of compilers. By default, if no other configuration file or directory is specified,
+ the configuration is created at <install_dir>/config/coverity_config.xml. Each invocation of cov-configure adds a compiler configuration
+ in its own subdirectory of the directory containing the coverity_config.xml file, and coverity_config.xml contains an include directive for
+ that compiler-specific configuration.
+
+- These configuration files are generated by ``run-coverity-configure`` target.
+- If the configuration options need to be changed, then define a ``coverity.config.options`` reference in the respective configuration file.
+
+Ex:
+
+.. code-block:: xml
+
+ <hlm:coverityoptions id="coverity.config.options">
+ <hlm:arg name="--config" value="${coverity.config.dir}/coverity_config.xml"/>
+ <hlm:arg name="--template" value=""/>
+ <hlm:arg name="--comptype" value="armcc"/>
+ <hlm:arg name="--compiler" value="armcc.exe"/>
+ </hlm:coverityoptions>
+
+Coverity build
+::::::::::::::::::::::::
+
+ The cov-build command intercepts all calls to the compiler invoked by the build system.
+
+ Usually the cov-build command name and option can prefix the original build command. However, if the build command depends on features
+ of the command shell that usually invokes it, such as certain shell variables or non-alphanumeric arguments, you can invoke it using a
+ wrapper script. This preserves the original behavior because the build command is again invoked directly by the kind of shell on which
+ it depends.
+
+- Coverity Prevent tool build command integrated with SBS task.
+- Coverity task extends the "sbstask", so what ever the arguments we pass for sbstask will remain same for coverity tool also.
+- For example
+
+.. code-block:: xml
+
+ <hlm:coveritybuild sbsinput="@{sbs.input}"
+ sysdeffile="${build.drive}/output/build/canonical_system_definition_${sysdef.configuration}.xml"
+ layerpatternsetref="${sbs.patternset}"
+ workingdir="${build.drive}/"
+ execute="true"
+ failonerror="false"
+ outputlog="${sbs.log.file}"
+ cleanlog = "${sbs.clean.log}"
+ erroroutput="${sbs.log.file}.sbs_error.log"
+ statslog="${sbs.log.file}.info.xml">
+ <hlm:coverityoptions refid="coverity.build.options"/>
+ </hlm:coveritybuild>
+
+- In above example Coverity Prevent tool is integrated with sbs using task "coveritybuild".
+- This task is slightly difference from sbstask as it accepts the coverity tool parameters required while running coverity tool.
+- In the above example we have mentioned "coverity.build.options" which are required for cov-build command.
+- coverityoptions datatype will follow below syntax.
+
+.. code-block:: xml
+
+ <hlm:coverityoptions id="coverity.build.options">
+ <arg name="--config" value="${coverity.config.dir}/coverity_config.xml"/>
+ <arg name="--dir" value="${coverity.inter.dir}"/>
+ <arg name="--auto-diff" value=""/>
+ <arg name="--preprocess-first" value=""/>
+ <arg name="--record-only" value=""/>
+ </hlm:coverityoptions>
+
+- Internally "coveritybuild" task will run the "cov-build" with parameters passed with "<hlm:coverityoptions>" datatype and sbs commands.
+- Above arguments are passed by default in helium. If it is required to remove/change the default parameters (by helium)into cov-build,
+ we need to override the datatype "coverityoptions".
+
+- Command resulted for above example is shown below with "@{sbs.input} = dfs_build_input_armv5".
+
+ | cov-build.exe --auto-diff --record-only --config Y:/output/coverity/config/coverity_config.xml
+ | --preprocess-first --dir Y:/output/coverity/intermediate sbs -s Y:/output/build/canonical_system_definition_dfs_build.xml
+ | -c armv5 -k --logfile Y:/output/logs/compile/ido_helloworld_tb92_blr_ci_9.2.30_armv5_dfs_build.log
+ | --makefile=Y:/output/logs/compile/ido_helloworld_tb92_blr_ci_9.2.30_armv5_dfs_build
+
+Coverity emit
+::::::::::::::::::::::::
+
+ The ``cov-emit`` command parses a source file and outputs it into a directory (emit repository) that can later be analyzed with ``cov-analyze``.
+ The ``cov-emit`` command is typically called by ``cov-translate``, which is in turn typically called by ``cov-build`` (``cov-emit`` is a low-level command
+ and is not normally called directly).
+
+ Re-running the cov-build with replay option will reduce the build time by ~ 20%
+
+ - Coverity emit command run by target ``run-coverity-emit``.
+
+Coverity analyze
+::::::::::::::::::::::::
+
+ Sometimes the same file is compiled several times with different command-line options. Due to the inherent difficulty of tracking linkage
+ information, the ``cov-analyze`` command cannot automatically determine which files are linked together. To avoid errors in function call
+ resolution (especially in C code, which doesn't have any name mangling), use the ``cov-link`` command to get this information.
+
+ and also
+
+ working with link files is faster than collecting data from the intermediate directory multiple times
+
+ So run the ``cov-link`` commands and analyze the database using ``cov-analyze`` command.
+
+- Coverity code analysis is done by target ``run-coverity-analyze``.
+- Analysis is done in 2 stages. First runs ``cov-link`` and then ``cov-analyze`` command.
+
+**cov-link command**
+
+ 1. Run cov-link with the --collect and -of options to collect linkage information on all files compiled in an emit directory.
+
+ 2. Create one or more additional link files by filtering information using either an argument or a portion of the pathname that
+ was used during command-line compilation. Compiled files are identified based on:
+ * A portion of the pathname to the file when it was compiled. Use the -s option to specify a Perl regular expression to use when looking
+ at the pathname.
+
+ * The options given on the command line when it was compiled. Use the -a, -r, -na, and -nr options to group by command-line options.
+
+ 3. Use the link files created in the previous steps, and the emit repository in the original intermediate directory, to create a new intermediate directory with an emit repository with resolved function calls. Then use cov-analyze on the new intermediate directory.
+
+**cov-analyze**
+ command analyzes the code previously parsed and emitted into an intermediate directory. The result is a set of XML files
+ in the <intermediate_directory>/c/output directory that contain a description of the defects. The cov-analyze command also stores analysis
+ information in the intermediate directory, which speeds up future runs.
+
+ A log file with information about the checkers used in the analysis, including notices of crashes, is created at
+ <intermediate_directory>/c/output/analysis-log.txt.gz.
+
+ Note that behind the scenes, cov-analyze actually calls cov-internal-analyze-c to run the analysis. If you look at running processes,
+ both cov-analyze and cov-internal-analyze-c are listed. During an analysis, cov-analyze monitors cov-internal-analyze-c, and can
+ seamlessly restart the analysis in case of failure.
+
+ - ``coverity.analyze.options`` could be set if it required to disable/enable the checkers.
+
+ .. code-block:: xml
+
+ <hlm:coverityoptions id="coverity.analyze.options">
+ <hlm:arg name="--dir" value="${coverity.analyze.dir}"/>
+ <hlm:arg name="--all" value=""/>
+ <hlm:arg name="--symbian" value=""/>
+ <hlm:arg name="--append" value=""/>
+ <hlm:arg name="--enable-callgraph-metrics" value=""/>
+ </hlm:coverityoptions>
+
+
+Coverity defect manager
+:::::::::::::::::::::::
+
+ The ``cov-commit-defects`` command takes defects stored as *.errors.xml files in the <intermediate directory>/<domain>/output directory and
+ commits them to the Defect Manager database as a new product run. Once committed, you can view the defects in the Defect Manager alongside
+ the source code that generated them. The defect XML files are created by the ``cov-analyze``command, which scan and evaluate the
+ preprocessed source files in the <intermediate directory>/<domain>/emit directory.
+
+- Coverity defects can be submitted to a remote coverity defect database using the ``run-commit-defects`` target.
+- To enable the target user should set ``coverity.commit.defects.enabled`` to ``true`` and ``coverity.enabled`` to ``true``.
+- Username and Password for the Coverity Defect Manager should be set in the `.netrc file`_::
+
+ machine coverity login <user name> password <password>
+
+.. csv-table:: Coverity feature flags
+ :header: "Flags to set", "Action performed", "Allowed value"
+
+ ":hlm-t:`coverity.commit.defects.enabled`", "If user wants to commit the defects using existing intermediate folder and run target
+ ``run-commit-defects``", "true/false"
+ ":hlm-t:`coverity.commit.defects.enabled` and `coverity.enabled`", "If user want to generate the intermididate folder and then commit
+ defects, first intermediate folders will get generated and defects will commited into database. By default this build sequence will
+ happen.", "true/false"
+
+- Below properties must be set for defects to be committed to the database:
+
+.. csv-table:: Coverity defect manager properties
+ :header: "Property name", "Description"
+
+ ":hlm-t:`coverity.defect.manager.server`", "Coverity defect manager server/IP address. Ex: server.domain.extension or 100.220.530.101"
+ ":hlm-t:`coverity.defect.manager.port`", "Coverity defect manager HTTP port number"
+ ":hlm-t:`coverity.defect.manager.product`", "Coverity defect manager product/platform to submit the coverity errors."
+