From 9b08a97d46f75fae33682dfd97a77a83eebfb556 Mon Sep 17 00:00:00 2001 From: Alex Tereschenko Date: Sun, 28 Jan 2018 15:34:50 +0100 Subject: [PATCH] docs: add static code analysis documentation Fixes #782. Signed-off-by: Alex Tereschenko --- docs/building.md | 12 ----- docs/index.md | 4 ++ docs/static_code_analysis.md | 93 ++++++++++++++++++++++++++++++++++++ 3 files changed, 97 insertions(+), 12 deletions(-) create mode 100644 docs/static_code_analysis.md diff --git a/docs/building.md b/docs/building.md index cf8fcd6..86a79c1 100644 --- a/docs/building.md +++ b/docs/building.md @@ -139,18 +139,6 @@ cmake -DCMAKE_TOOLCHAIN_FILE=../cmake/Toolchains/oe-sdk_cross.cmake .. make ~~~~~~~~~~~~~ -## Using Coverity - -This is the procedure to submit a build to Coverity. You'll need to install -`coverity-submit` for your OS. - -~~~~~~~~~~~~~{.sh} -mkdir covbuild/ && cd covbuild -cmake -DBUILDDOC=OFF -DBUILDSWIG=OFF .. -cov-build --dir cov-int make -tar caf mraa.tar.bz2 cov-int -~~~~~~~~~~~~~ - ## Building Java bindings Have JAVA_HOME set to JDK install directory. Most distributions set this from `/etc/profile.d/` diff --git a/docs/index.md b/docs/index.md index 4e884c0..c18daa1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -71,6 +71,10 @@ glance at our @ref debugging page too More information on compiling is @ref building page. +## STATIC CODE ANALYSIS + +See @ref static_code_analysis page. + ## CONTRIBUTING Please see the @ref contributing page, the @ref internals page may also be of diff --git a/docs/static_code_analysis.md b/docs/static_code_analysis.md new file mode 100644 index 0000000..52b2d24 --- /dev/null +++ b/docs/static_code_analysis.md @@ -0,0 +1,93 @@ +Static code analysis {#static_code_analysis} +==================== + +We use [SonarQube](https://www.sonarqube.org/) for static code analysis scans. +These are automated via Travis, same as our usual builds. + +Automated scans +--------------- + +We don't use the Travis' plugin for Sonar due to the fact we use Docker +and not the bare Travis, and these two are not compatible. + +We have a dedicated `docker-compose` target for scans, `sonar-scan`. Necessary +values are passed to Sonar scanner as command-line parameters. + +For the whole config to work, the following one-time configuration steps are necessary: +* Create organization and project in SonarQube - done already, + https://sonarcloud.io/organizations/mraa-github (key: mraa-github) + and https://sonarcloud.io/dashboard?id=mraa-master (key: mraa-master); +* Create technical account on GitHub with push permissions for mraa repo. + It is used for reporting pull request statuses in the "checks" area. + We have `intel-iot-devkit-helperbot` for this, shared with UPM. +* Add several environment variables in Travis: + * `GITHUB_TOKEN` (secure) - GH OAuth token for the technical user, + with `public_repo` privileges only; + * `SONAR_TOKEN` (secure) - this one comes from the SonarQube org properties; + * `SONAR_ORG`, `SONAR_PROJ_KEY` (may be public) - project and org keys (names) + from SonarQube org, see above; + +These scans are executed each time there's an internal pull request (from a branch +local to main mraa repo) or a `master` branch push. +Upon the former the so called "preview" scan is executed, which doesn't +upload anything to SonarQube organization and only reports the result within the PR. +Upon `master` branch push a normal scan is executed and results are uploaded to +SonarQube. + +When there's a so called "external" pull request (originating somewhere else +than mraa's main repo, e.g. from a fork), no scan is done for +security reasons, as code within such PR would have access to tokens listed above. + +In view of such setup, it's beneficial to create internal pull requests as much +as possible, because you'll catch problems right away - in the preview scan, +before PR is merged. + +Manual scans +------------ + +It's a good practice to run the scan manually before actually submitting a PR. +There may also be a need to run the scan manually out-of-cycle, so here's how. + +Just use the command line from [the scanner script](../master/scripts/sonar-scan.sh). +See `sonar_cmd_base` variable specifically and just replace various tokens +listed there with proper ones. Please also don't forget that you need to run the +build wrapper first, so that the scanner knows what to scan. + +The set of commands for the main mraa repo and SonarQube project would look like +the below. Note that it will upload results to the SonarQube by default, +if you don't want that, setup a throwaway "project" in SonarQube, or create a +separate "organization" dedicated to your mraa repo fork: + +```bash +$> export PATH=~/bin/sonar/sonar-scanner-3.0.3.778-linux/bin/:~/bin/sonar/build-wrapper-linux-x86/:$PATH +$> build-wrapper-linux-x86-64 --out-dir bw-output make clean all +$> sonar-scanner \ + -Dsonar.projectKey=mraa-master \ + -Dsonar.projectBaseDir=/PATH/TO/YOUR/MRAA/REPO/CLONE \ + -Dsonar.sources=/PATH/TO/YOUR/MRAA/REPO/CLONE \ + -Dsonar.inclusions='api/**/*,CMakeLists.txt,examples/**/*,imraa/**/*,include/**/*,src/*,src/**/*,tests/**/*' \ + -Dsonar.cfamily.build-wrapper-output=/PATH/TO/YOUR/MRAA/REPO/CLONE/YOUR_BUILD_DIR/bw-output \ + -Dsonar.host.url=https://sonarqube.com \ + -Dsonar.organization=mraa-github \ + -Dsonar.login=YOUR_SONAR_LOGIN_TOKEN_HERE +``` + +Notice that we first set the `PATH` to point to our downloaded copy of Sonar tools. +You can find more information on setting these up in SonarQube's nice +[Getting Started tutorial](https://about.sonarcloud.io/get-started/). + +Using Coverity +-------------- + +In the past we've used Coverity to do static code analysis scans. Below is the +documentation on that setup - for archiving purposes. + +This is the procedure to submit a build to Coverity. You'll need to install +`coverity-submit` for your OS. + +```bash +mkdir covbuild/ && cd covbuild +cmake -DBUILDDOC=OFF -DBUILDSWIG=OFF .. +cov-build --dir cov-int make +tar caf mraa.tar.bz2 cov-int +```