lequal/sonar-scanner-vhdl repository overview

⁠CNES sonar-scanner image dedicated to VHDL [client]

This image is a pre-configured sonar-scanner image derived from Docker-CAT⁠. It contains only tools for VHDL code analysis and it is available on Docker Hub at lequal/sonar-scanner-vhdl⁠.

SonarQube itself is an opensource project on GitHub: SonarSource/sonarqube⁠.

For versions and changelog: GitHub Releases⁠.

:information_source: If you only need a containerized sonar-scanner, you better use the official image from SonarSource available on Docker Hub: sonarsource/sonar-scanner-cli⁠. The official image is smaller because it does not embed any other tool.

⁠Features

Compared to the official sonarsource/sonar-scanner-cli⁠ image, this image provides additional features.

Additional features are:

• Embedded tools
  • see the list⁠

This image is made to be used in conjunction with a pre-configured SonarQube server image that embeds all necessary VHDL plugins and configuration: cnescatlab/sonarqube⁠. It is, however, not mandatory to use it.

⁠User guide

1. Write a sonar-project.properties at the root of your project
   • For information on what to write in it, see the official SonarQube documentation⁠
2. Execute the sonar-scanner on the project by running this image from the root of the project

   $ docker run \
           --rm \
           -u "$(id -u):$(id -g)" \
           -e SONAR_HOST_URL="url of your SonarQube instance" \
           -v "$(pwd):/usr/src" \
           lequal/sonar-scanner-vhdl
   

   Copy
   This docker command is equivalent to sonar-scanner -Dsonar.host.url="url of your SonarQube instance".
   • If the SonarQube server is running in a container on the same computer, you will need to connect both containers (server and client) to the same bridge so that they can communicate. To do so:

     $ docker network create -d bridge sonarbridge
     $ docker network connect sonarbridge "name of your sonarqube container"
     # add the following option to the command line when running the lequal/sonar-scanner-vhdl
     --net sonarbridge
     

     Copy
   • To find you server IP you can execute the following commands:
     Get the sonarqube server Container ID by running:

     docker ps
     

     Copy
     Use this Container ID to get the dedicated IP address:

     docker inspect -f '{{range .NetworkSettings.Networks}} {{.IPAddress}}{{end}}' <MySonarqubeDockerID>
     

     Copy

This image suffers from the same limitations as the official SonarQube sonarsource/sonar-scanner-cli⁠ image.

• If you want to save the sonar-scanner cache, you must create the directory to bind mount in the container before running it. For more information, see SonarQube documentation⁠.

⁠Examples usage in CI

To be done

⁠GitHub Actions

Here is a GitHub Actions job of a GitHub Actions workflow that call this image to analyze a project.

jobs:
  sonar-scanning:
    name: Run CNES sonar-scanner-vhdl
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Cache sonar-scanner data
        uses: actions/cache@v2
        with:
          path: .sonarcache
          key: sonar-scanner-cache
      - run: |
          mkdir -p .sonarcache
          docker run --rm \
                    -u "$(id -u):$(id -g)" \
                    -e SONAR_HOST_URL="https://my-sonarqube.com" \
                    -v "$(pwd):/usr/src" \
                    -v ".sonarcache:/opt/sonar-scanner/.sonar/cache" \
                    lequal/sonar-scanner-vhdl

⁠GitLab-CI

Here is GitLab-CI job, in a .gitlab-ci.yml, to analyze a project with this image.

sonar-scanning:
  stage: test
  cache:
    key: sonar-scanner-job
    paths:
      - .sonarcache
  script:
    - mkdir -p .sonarcache
    - docker run --rm \
              -u "$(id -u):$(id -g)" \
              -e SONAR_HOST_URL="https://my-sonarqube.com" \
              -v "$(pwd):/usr/src" \
              -v ".sonarcache:/opt/sonar-scanner/.sonar/cache" \
              lequal/sonar-scanner-vhdl

⁠Analysis tools included

⁠Developer's guide

Note about branch naming: if a new feature needs modifications to be made both on the server image and this one, it is strongly advised to give the same name to the branches on both repositories because the CI workflow of this image will try to use the server image built from the same branch.

⁠How to build the image

It is a normal docker image. Thus, it can be built with the following commands.

# from the root of the project
$ docker build -t lequal/sonar-scanner-vhdl .

To then run a container with this image see the user guide⁠.

To run the tests and create your own ones see the test documentation⁠.

⁠Debugging the image

If analysis doesn't perform correctly you can inspect the image by doing the following sequence:

1. launch the container with a shell (the entrypoint script is not ran).
   In this case, a bridge was created as sonarbridge to link with the soanrqube container which can be address with IP 172.18.0.2. Notice that the container was given a name : lequalscanner.

docker run --name lequalscannervhdl --net sonarbridge --rm  -e SONAR_HOST_URL="http://172.18.0.2:9000" -it --entrypoint /bin/sh lequal/sonar-scanner-vhdl 

1. Run the following script (on a new windows powershell)

#get container ID and store it in a variable
$DOCKERID=docker ps -aqf "name=lequalscannervhdl"  
#copy your sources in the scanner container (you're supposed to be located in your sources directory when executing this script)
docker cp .  ${DOCKERID}:/usr/src
#change ownership of the sources
docker exec -u root  ${DOCKERID} bash -c 'chown -R sonar-scanner:sonar-scanner /usr/src'

1. Do what ever you needed to be done. You can launch sonar scanner analysis by running the following command in the container shell and then debug the result

entrypoint.sh -X.

⁠How to contribute

If you experienced a problem with the image please open an issue. Inside this issue please explain us how to reproduce this issue and paste the log.

If you want to do a PR, please put inside of it the reason of this pull request. If this pull request fixes an issue please insert the number of the issue or explain inside of the PR how to reproduce this issue.

All details are available in CONTRIBUTING⁠.

Bugs and feature requests: issues⁠

To contribute to the project, read this⁠ about CATLab's workflows for Docker images.

⁠License

Licensed under the GNU General Public License, Version 3.0⁠

This project is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.