This tool aims to make submitting projects for code auditing on the demonstration Coverity server into a one-step operation. It automates the sequence of (a) running cov-build locally, (b) bundling the results into a tarball with a properly formatted README, (c) submitting a tarball and analysis request to the server, and (d) retrieving the request status.
Once you have the enabling metadata data for a project set up, you can usually submit an analysis job just by running coverity-submit without arguments. The Coverity analyzer will email you a success or failure notification when the analysis results are available.
To use this tool, you need to set up a configuration file named
either .coverity-submit or
.config/coverity-submit in your home directory.
This configuration file is best explained by example.
[ALL] name: Eric S. Raymond userid: esr email: esr@thyrsus.com tools: /usr/local/coverity/bin [gpsd] token: XXXXXX prebuild: scons -c build: scons postbuild: [giflib] token: YYYYYYY prebuild: autogen.sh && make clean build: make -k postbuild: [cvs-fast-export] name: parsecvs token: ZZZZZZZ prebuild: make clean build: make postbuild: [ntpsec] name: ntpsec token: AAAAAAA prebuild: ./waf clean build: ./waf postbuild:
You may begin with an [ALL] section giving your name and userid on the Coverity server. If you don't specify these, the tool will use your local usename and the first (comma-separated) portion of your GECOS field.
You may specify the email address to which success or failure notifications should be mailed for all other projects here, or specify different addresses per-project.
If cov-build is not in your execution path, you may use the 'tools' option to tell coverity-submit where to find it.
This configuration describes four different (real) projects; one with an scons-based build, one with an autotools-based build, one with a plain makefile build, and one with a waf build. For each project you must specify the project's authentication token and the local build command to pass to cov-build. You may optionally specify local prebuild and postbuild commands.
The third example also illustrates how to describe a project that is known to Coverity by a different name (in this case “parsecvs”) from the basename of the directory you keep it in (in this case “cvs-fast-export”). This can of course easily happen if your project's public name changes after you register it.
The first thing coverity-submit does when invoked is figure out which project profile to use. If no argument is specified but the basename of the current directory matches a project, it is selected. Otherwise, a command-line argument can specify the project name; it is a fatal error for the argument, if given, not to match the name of one of the configured project profiles.
Note: because your configuration file contains privileged information (the per-project Coverity authentication tokens) it should not have read or write permissions for anyone but its owner set. When coverity-submit detects such insecure permissions, it will fix them (telling you it is doing so).
The -n option says to display all the commands that
would be run without actually executing them. The -v option
enables slightly more verbose progress messages, and copies the Coverity
build-log.txt from the run to your working directory.
The -b option specifies an arbitrary build
version to associate with the submission. If coverity-submit is run
at the top level of a version-control repository, the build version may
default to a description of the head commit; presently this feature
is supported under git, hg, bzr, and svn.
The -t option specifies an arbitrary project
tag or description to associate with the submission. This text is
visible in the "snapshots" view of the Coverity web interface. If you
do not specify a description, the ISO8601 date that the submission
was initiated is used.
Once coverity-submit has determined which project profile to use, it then performs the following steps:
The project's local prebuild command, if specified.
The project's local build command.
The project's local postbuild command, if specified.
Generating a README and bundling it into a tarball with the scan results.
Sending the tarball and an analysis job request to the Coverity server.
The script will report the result of the job request by dumping the server's HTML response.
If, after a period of normal operation, you see a complaint that no compilation units are being built, this may mean your version of the Coverity build tools has gone stale. This has been known to happen on GCC version bumps. Try installing an-up-to-date version of the tools.
For backward compatibity, 'password' is treated as a synonym for 'token'; the change follows a change in the terminology of Coverity's configuration instructions.
The build and advertise
options of versions 1.1 and previously are no longer needed, as
Coverity has changed its submission form to support direct upload of
the results tarball.
Requires Python, curl, and cov-build.
The Coverity Scan facility has a home page: https://scan.coverity.com. You can find instructions on how to register projects for scanning there.
Eric S. Raymond <esr@thyrsus.com>. There is a
project page for this tool at http://www.catb.org/~esr/coverity-submit/coverity-submit.html.