Code Coverage

Use of gcov/lcov is supported with the gnu compiler and is currently working on Derecho. Coverage testing is turned on at the cice.setup and icepack.setup command line with the --coverage argument. That typically looks like

./cice.setup --suite first_suite,prod_suite,base_suite,travis_suite,decomp_suite,reprosum_suite,io_suite,omp_suite,gridsys_suite,perf_suite,quick_suite,unittest_suite -m derecho -e gnu --testid T${date} --coverage

or

./icepack.setup --suite base_suite,io_suite,travis_suite,quick_suite -m derecho -e gnu --testid T${date} --coverage

The --coverage flag does several things. The ICE_COVERAGE flag is set to true in the icepack.settings or cice.settings file. This triggers extra compiler flags

FFLAGS   += -O0 -g -fprofile-arcs -ftest-coverage
CFLAGS   += -O0 -g -coverage
LDFLAGS  += -g -ftest-coverage -fprofile-arcs

set in the configuration/scripts/machines/Macros file. Finally, a post-processing script, report_lcov.csh is run after the suite is complete. This extracts the coverage information and then posts the results at https://apcraig.github.io/. For CICE, there are some extra steps. The CICE sandbox is copied to a new location before compilation begins and !LCOV_EXCL_LINE are added to the end of Fortran continuation lines to improve coverage reporting.

The post-processing part of coverage testing can be time consuming.

---

The Process below is no longer used, but will be preserved for historical purposes.

---

Check if lcov already exists

On some machines, lcov is already installed either on the system or by someone in the Consortium. You can try

source configurations/scripts/machines/env.${mach}_${env}
which lcov
perl -e 'use PerlIO::gzip;'

If those don't return errors, you are probably OK. If not,

Download lcov

git clone https://github.com/linux-test-project/lcov.git
cd lcov

Install lcov in your local directory

Install in your $HOME

make install PREFIX= DESTDIR=~

lcov and supporting scripts has now been added to your ~/bin directory. Add that path to your PATH if it doesn't already exist. A good place to put this is in the env.${mach}_${env} file. This has been done for a couple machines as follows,

set lcovpath = "/glade/u/home/tcraig/bin"

if ($?PATH) then
  if ("$PATH" !~ "*${lcovpath}*") then
    setenv PATH ${PATH}:$lcovpath
  endif
else
  setenv PATH $lcovpath
endif

Install PerlIO-gzip

Check whether PerlIO-gzip is already installed

perl -e 'use PerlIO::gzip;'

If this returns nothing, you're OK. If it returns "Can't Locate PerlIO/gzip.pm in @INC ..." then you'll have to install that Perl module yourself. If you can install it as root or if you can get your sys admins to install it, that's the best long term solution. But if that's not an option, you'll have to install PerlIO-gzip locally.

Setup compilation environment for the gnu compiler (this is machine specific)

module unload PrgEnv-cray
module unload PrgEnv-gnu
module unload PrgEnv-intel
module unload PrgEnv-pgi
module load PrgEnv-gnu/5.2.82
module unload gcc
module load gcc/6.3.0

Download and build PerlIO-gzip in your local directory

cd ~
mkdir perlio-gzip
cd perlio-gzip
wget --no-check-certificate https://cpan.metacpan.org/authors/id/N/NW/NWCLARK/PerlIO-gzip-0.20.tar.gz
gunzip PerlIO-gzip-0.20.tar.gz
tar -xvf PerlIO-gzip-0.20.tar
cd PerlIO-gzip-0.20
perl Makefile.PL DESTDIR=~
   # NOTE: if you are installing as root, you just want to do "perl Makefile.pl" above.
make
make test
make install

If you installed locally, this will be installed in something like ~/user/lib/perl5/site_perl/5.x.y/x86_64-linux-thread-multi/. Add that path to your PERL5LIB env variable. A good place to put this is in the env.${mach}_${env} file. This has been done for a couple machines as follows,

set lcovp5l  = "/glade/u/home/tcraig/usr/lib/perl5/site_perl/5.18.2/x86_64-linux-thread-multi"

if ($?PERL5LIB) then
  if ("$PERL5LIB" !~ "*${lcovp5l}*") then
    setenv PERL5LIB ${PERL5LIB}:$lcovp5l
  endif
else
  setenv PERL5LIB $lcovp5l
endif

Setup automated push to web page

You may need to request write access to the lcov results webpage

https://github.com/apcraig/apcraig.github.io

Please contact the consortium for more information. In addition, you may want to add

[credential "https://github.com/apcraig/apcraig.github.io"]
helper = store

to your .gitconfig file. This will remember the login and password of the credential github site after first use and will allow push to the website without username/password.

You should now be able to run report_lcov.csh as part of testing coverage.