






























































                       June 23, 1992





                             2





                    GCT Troubleshooting


                        Brian Marick
                    Testing Foundations

            Documentation for version 1.3 of GCT
                    Document version 1.2





This manual gives solutions to common GCT problems.   Please
send problem reports to me (address on next page), so that I
can improve the next version of this document.

Troubles specific to weak mutation  (operand  and  operator)
coverage  are  handled  in _U_s_i_n_g _W_e_a_k _M_u_t_a_t_i_o_n _C_o_v_e_r_a_g_e _w_i_t_h
_G_C_T.


































                       June 23, 1992








_P_r_e_f_a_c_e



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

GCT is distributed in the hope that it will be  useful,  but
WITHOUT  ANY  WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A  PARTICULAR  PURPOSE.   See
the GNU General Public License for more details.



For more information about  GCT  or  the  other  services  I
offer, contact:

Brian Marick
Testing Foundations
809 Balboa
Champaign, Illinois  61820

(217) 351-7228
Email: marick@cs.uiuc.edu

You can join the GCT mailing list by sending  mail  to  gct-
request@ernie.cs.uiuc.edu.
















This document is Copyright 8c9 1992 by Brian Marick.  Portions
are  Copyright  8c9 1991 by Motorola, Inc.  Under an agreement
between Motorola, Inc., and Brian Marick,  Brian  Marick  is
granted rights to these portions.

Brian Marick hereby permits you to reproduce  this  document
for personal use.  You may not reproduce it for profit.





                       June 23, 1992





                             2                Documentation


If you have a problem with GCT, search for the  symptom  (in
bold, below), then read the following text.

_1.  _T_r_o_u_b_l_e _I_n_s_t_r_u_m_e_n_t_i_n_g _y_o_u_r _S_y_s_t_e_m

Files not instrumented
     Is the file in the control file?

     If you are using a makefile, is the source  file  newer
     than the object file?  Normally, grestore ensures this.
     However,  copying  files  to  the  test  directory  (or
     extracting  them  from  a configuration control system)
     can leave object files newer than source files.

Warning when compiling gct-ps-defs.c
     "gct-ps-defs", line 10: warning: zero or negative subscript

     This warning means that no file was instrumented.   See
     _F_i_l_e_s _n_o_t _i_n_s_t_r_u_m_e_n_t_e_d, above.

Make fails on non-compilation commands
     When using gct with a makefile, there  is  a  recursive
     invocation of the makefile:

          $(MAKE) all "CC=gct"

     In some cases, the actions performed  by  the  makefile
     fail unless $(CC) creates an object or executable file.
     A typical example is a make target like this:

          all: $(OBJ)
              $(CC) -o temp $(OBJ)
              mv temp final

     The mv fails because temp is not created.  In many ver-
     sions  of make, you can use make -k to print error mes-
     sages  and  continue.   This  also  ignores  legitimate
     errors, so examine the make log carefully.

     In some cases, the recursive call can be preceded by  a
     minus sign:

          -$(MAKE) all "CC=btool"

     but in other cases the makefile must  be  changed  more
     extensively  to  put  minus signs in front of many non-
     compilation actions.

#pragmas within functions are dangerous.
     All pragmas in the original source are copied into  the
     instrumented  source.   Instrumentation rearranges code
     within functions.  If the pragma is within  a  function
     and  is  intended  to  apply  to  a following token (or
     expression, or statement), that token might  have  been



                       June 23, 1992





                             3                Documentation


     moved.   Some other token might follow the pragma.  The
     original token might even have been  moved  before  the
     pragma.

     This is less likely to be a problem if  the  pragma  is
     between  statements  or  inside  declarations,  but you
     should  check  the  instrumented  code  to  make  sure.
     Instrumentation  never rearranges code outside of func-
     tions.

     This version of GCT cannot tell  whether  a  pragma  is
     within a function, so the warning is often spurious.

GCT warns about variable-length argument lists.
     GCT issues this warning when it sees you've  written  a
     function  with  a  variable-length  argument  list on a
     machine where such functions may  have  to  be  handled
     specially.   This note explains the problem, what to do
     about it, and how to find out if you have it.

     In C, variable-length argument  lists  are  implemented
     using  the  va_start(),  va_arg(), and va_end() macros.
     You  define  them  to   your   program   by   including
     <varargs.h>  (for pre-ANSI programs) or <stdarg.h> (for
     ANSI-compliant programs).   GCT  expands  these  macros
     during  instrumentation, just as it expands all macros.
     Unfortunately, <varargs.h>  and  <stdarg.h>  are  often
     written   expecting  a  particular  compiler,  and  the
     expanded macros will only work with that compiler.   If
     so, the versions in /_u_s_r/_i_n_c_l_u_d_e work with the standard
     C compiler (/_b_i_n/_c_c), and other compilers are  expected
     to  have  their  own  private copies of <varargs.h> and
     <stdarg.h>.

     So, on some machines, GCT must  "know"  which  compiler
     you'll use to compile the instrumented file, so that it
     can  include  the  appropriate  files.   Normally,   it
     expects you to use "cc", but it might have been config-
     ured differently.  If you don't use  the  compiler  GCT
     expects,  you  may  have  to tell it which one you will
     use.  This is done with the -test-cc option.  For exam-
     ple,  if  you  use  "gcc",  you would do something like
     this:

         gct -test-cc gcc varargs.c
         gcc varargs.c


     You need to give the  -test-cc  argument  even  if  the
     function  with  a  variable  number of arguments is not
     instrumented, but is only included in a file with other
     functions that are.

     To find out the status of your machine, type



                       June 23, 1992





                             4                Documentation


         gct -test-varargs

     The output tells you which different compilers you  can
     use,  how  to  invoke  GCT,  and how well varargs-using
     functions work.  In the best case, alternate  compilers
     can be freely substituted for the default and you don't
     have to worry about -test-cc.

     If the compiler you use is not mentioned in the output,
     contact   the  GCT  installer.   The  GCT  installation
     instructions describe scripts you can use  to  discover
     how to use your compiler with GCT.

Control file not found with multi-directory makefiles
     Have you given the -test-dir argument to gct?

     Is the argument correct?   When  using  `pwd`  in  your
     makefile  to  find the current directory, you must make
     sure it is evaluated at the right time.   For  example,
     if  your  makefile  does  not  call  itself, but rather
     changes its directory and calls another  makefile,  the
     following will _n_o_t work:

     gct:
          gct-init;
          cd subdir; $(MAKE) all "CC=gct -test-dir `pwd`"
          ...

     pwd is not evaluated until after  the  cd.   A  correct
     solution is

     gct:
          gct-init;
          MYDIR=`pwd`; cd subdir; $(MAKE) all "CC=gct -test-dir $$MYDIR"
          ...

     (Note the double dollar signs, which prevent make  from
     evaluating "$M" as one of its variables.)

gct-init: gct-init: No such file or directory
     If you see this message when using your makefile,  your
     version  of  make has a bug.  Add a semicolon after the
     call to gct-init.

Compiler Dependencies
     Some programs take advantage of the fact that they  are
     compiled by the GNU C compiler. They refer to functions
     or features supported by gcc  but  not  by  other  com-
     pilers.  The  commmon  way  to  do  that  is by testing
     whether the actual  compiler  is  gcc  or  not:  #ifdef
     __GNUC__

     Since gct is a modified GNU gcc, the #ifdef __GNUC__ is
     evaluated to 1. If you compile the instrumented version



                       June 23, 1992





                             5                Documentation


     of the source code with any other  compiler,  difficul-
     ties  might occur. In this case you must change the #if
     to something that will evaluated to 0 (e.g.  __XGNUC__)
     or place

     #undef __GNUC__

     in a common include file.

Compiling with non-ANSI C compilers:  __STDC__
     gct defines __STDC__ to indicate that it accepts  ANSI-
     compliant C code.  If the source has code like

     #ifdef __STDC__
          /* Code dependent on having an ANSI compiler. */
     #endif

     the ANSI-dependent code will be included in the instru-
     mented source.  Then compiling with a non-ANSI compiler
     may lead to compile errors. The solution is to give the
     -traditional switch to gct, which causes it to undefine
     __STDC__.  The -traditional switch is explained in  the
     gcc(1)  manpage,  which  is included with the distribu-
     tion.

gct finds compile errors.
     GCC, the compiler that gct is based on, sometimes finds
     legitimate errors that other C compilers miss.  You may
     have to correct the source.

     Some programs are dependent on  features  that  C  com-
     pilers  have  traditionally  supported but that are not
     part of the language. One example is using comments for
     token concatenation:

     #define concat(str1, str2)    str1/**/str2

     concat(x, 4) ==> x4

     The -traditional switch may persuade gct to  let  these
     programs  pass.   See  the  gcc(1)  manpage,  which  is
     included with the distribution.

_2.  _E_r_r_o_r_s _i_n _G_r_e_p_o_r_t _O_u_t_p_u_t

Mapfile and Logfile are inconsistent

     Here greport reports that the mapfile and logfile  have
     different  sizes.  The most likely cause is that you're
     using the wrong mapfile.   There's  one  obscure  case,
     though,  where  GCT creates an incorrect mapfile.  Sup-
     pose you've instrumented your program, you're  using  a
     mapfile  name other than _g_c_t-_m_a_p, and you decide to re-
     instrument.  The first step in the normal  sequence  is



                       June 23, 1992





                             6                Documentation


     gct-init,  which  removes  _g_c_t-_m_a_p.  It does not remove
     your mapfile, so GCT appends to it during  instrumenta-
     tion.  Since gct-init did initialize _g_c_t-_p_s-_d_e_f_s._h, the
     mapfile ends up twice the size of the log file.

     Solution:  Explicitly remove your mapfile each time you
     instrument  (in  addition  to  calling  gct-init).  (It
     would be better if gct-init took a -test-map option.

_3.  _T_r_o_u_b_l_e _W_o_r_k_i_n_g _w_i_t_h _G_r_e_p_o_r_t _O_u_t_p_u_t

Lines about included files in greport output
     You may be surprised  to  find  that  functions  in  an
     #included   file   are  instrumented,  even  when  that
     included file is not mentioned in the control file. The
     decision about whether to instrument or not is based on
     the filename passed to GCT, and that  decision  applies
     to all included files. There is no way around this.  It
     is almost certainly a design flaw, but  the  fix  isn't
     completely obvious.

Cannot rule out right-hand multicondition.
     In a test like A && B, people often are surprised  that
     B can be both true and false, but GCT will insist that

     "test.c", line 4: condition 2 (b, 1) was taken TRUE 1, FALSE 0 times.

     GCT obeys C's rules for short-circuit  evaluation.  The
     value of B is never tested unless A is true.  Not every
     execution where B is false will rule out this  coverage
     condition, only one where A!=0, B==0.

     It would not be safe to evaluate the right-hand side to
     see if coverage would be satisfied.  Consider

     ptr!=0 && ptr->field==5


Cannot rule out loop coverage for a do...while loop
     Most likely your tests are doing what  you  think  they
     are, but the greport output doesn't mean what you think
     it means.  This is a design flaw that  will  eventually
     be fixed.  In the meantime, see the description of loop
     coverage in the User's Manual.













                       June 23, 1992


