home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / C / SASC6571.LZX / examples / cover / READ.ME < prev    next >
Encoding:
Text File  |  1996-12-24  |  6.9 KB  |  226 lines
  1. COVERAGE ANALYSIS EXAMPLE
  2. Copyright (c) 1992-1993 SAS Institute, Inc, Cary, NC USA
  3. All Rights Reserved
  4. -------------------------
  5.  
  6. To use coverage analysis, you must compile your code with the "COVER"
  7. option enabled.  The SCOPTIONS file in this directory specifies the
  8. necessary options.  Do not use the OPTIMIZE option with COVER, since
  9. it will make the line number information inaccurate.
  10.  
  11. When you link your program, you must use one of the SAS/C provided 
  12. startup modules that supports autoinitialization and autotermination
  13. functions.  For example, c.o, cres.o, cback.o, catch.o, and libinitr.o
  14. will all work.
  15.  
  16. **** IMPORTANT ****  
  17. The order in which you execute the following steps in very important.  If
  18. you do  not execute the steps in this order, you may get incorrect
  19. results.  
  20.  
  21. If you have tried this example before, be sure to delete the file cover.dat
  22. from the current directory before running it again.
  23.  
  24.  
  25. TO RUN THE COVERAGE UTILITY, DO THE FOLLOWING FROM THE SHELL
  26. ------------------------------------------------------------
  27. 1. Enter the following command:
  28.  
  29.       SC test.c test2.c
  30.       
  31.    This will compile and link the test C source file so that its executable
  32.    includes the information needed by the coverage utility.  Note that
  33.    the SCOPTIONS file in this directory specifies the COVER option, so 
  34.    you do not need to specify it on the command line.  When you try to
  35.    apply coverage to your own projects, you will need to specify the
  36.    COVER option in your SCOPTIONS file or on the command line to
  37.    generate coverage analysis code.
  38.  
  39. ------------------------------------------------------------
  40. 2. Run the test program:
  41.  
  42.       test
  43.  
  44.    It will produce the output
  45.    
  46.       USAGE: test <number>
  47.  
  48.    Running test creates a file called cover.dat which contains
  49.    information about which lines were executed when you ran test.
  50.    
  51. ------------------------------------------------------------
  52. 3. Run the cover utility
  53.  
  54.       cover
  55.  
  56.    It will produce the output
  57.  
  58.       In file test.c
  59.                              37 Lines,       11 not executed
  60.       In file test2.c
  61.                               9 Lines,        4 not executed
  62.  
  63.    Running cover produces a file called test.cov and a file called test2.cov.
  64.    These files contain a copy of your test.c and test2.c source code.  They also 
  65.    contain arrows pointing to each line of your program that generates code which
  66.    was not executed.  A .cov file will be produced for every .c  that generated 
  67.    code.
  68.    
  69. ------------------------------------------------------------
  70. 4. Examine the first output file, test.cov.
  71.  
  72.       se test.cov
  73.  
  74.    What you will see in the editor is the following.  The lines prefaced
  75.    by arrows (==>) generated code but were not executed in this run.
  76.  
  77.            1  #include <stdio.h>
  78.            2  #include <stdlib.h>
  79.            3  
  80.            4  int test2(int);
  81.            5  
  82.            6  int main(int argc, char *argv[])
  83.            7  {
  84.            8     int num;
  85.            9  
  86.           10     if(argc<2)
  87.           11     {
  88.           12        fprintf(stderr, "USAGE: test <number>\n");
  89.           13        exit(20);
  90.           14     }
  91.           15  
  92. ==>       16     num = atoi(argv[1]);
  93. ==>       17     if(num < 0)
  94.           18     {
  95. ==>       19        printf("Number is negative\n");
  96.           20     }
  97. ==>       21     else if(num<10)
  98.           22     {
  99. ==>       23        printf("0 <= Number < 10\n");
  100.           24     }
  101. ==>       25     else if(num <100)
  102.           26     {
  103. ==>       27        printf("10 <= Number < 100\n");
  104.           28     }
  105. ==>       29     else
  106.           30     {
  107. ==>       31        printf("Number >= 100\n");
  108.           32     }
  109.           33  
  110. ==>       34     test2(num);
  111.           35  
  112. ==>       36     return(0);
  113.           37  }
  114.  
  115.    Exit the editor and return to the Shell.
  116.  
  117. ------------------------------------------------------------
  118. 5. Run the program again with a valid option:
  119.  
  120.       test 10
  121.  
  122.    The program will produce the output
  123.  
  124.       10 <= Number < 100
  125.        
  126.    The cover.dat file will be updated to reflect the new paths taken through your 
  127.    code by this execution of test.     
  128.  
  129. ------------------------------------------------------------
  130. 6. Run the cover utility again:
  131.  
  132.       cover
  133.  
  134.    This time it generates the following message:
  135.  
  136.       In file test.c
  137.                              37 Lines,        4 not executed
  138.       In file test2.c
  139.                               9 Lines,        2 not executed
  140.   
  141.    The cover utility evaluates the updated information and produces new .cov files
  142.    that reflect which lines were and were not executed in both runs of the program.
  143.    
  144. ------------------------------------------------------------
  145. 7. Examine the new output file test.cov:
  146.  
  147.       se test.cov
  148.  
  149.    Notice that this time fewer arrows appear.  This is because the test
  150.    cases exercised more of the program.  The lines that still have arrows
  151.    were not executed either of the two times you ran the program.
  152.  
  153.            1  #include <stdio.h>
  154.            2  #include <stdlib.h>
  155.            3  
  156.            4  int test2(int);
  157.            5  
  158.            6  int main(int argc, char *argv[])
  159.            7  {
  160.            8     int num;
  161.            9  
  162.           10     if(argc<2)
  163.           11     {
  164.           12        fprintf(stderr, "USAGE: test <number>\n");
  165.           13        exit(20);
  166.           14     }
  167.           15  
  168.           16     num = atoi(argv[1]);
  169.           17     if(num < 0)
  170.           18     {
  171. ==>       19        printf("Number is negative\n");
  172.           20     }
  173.           21     else if(num<10)
  174.           22     {
  175. ==>       23        printf("0 <= Number < 10\n");
  176.           24     }
  177.           25     else if(num <100)
  178.           26     {
  179.           27        printf("10 <= Number < 100\n");
  180.           28     }
  181. ==>       29     else
  182.           30     {
  183. ==>       31        printf("Number >= 100\n");
  184.           32     }
  185.           33  
  186.           34     test2(num);
  187.           35  
  188.           36     return(0);
  189.           37  }
  190.  
  191.    Exit the editor and return to the Shell.
  192.  
  193. ------------------------------------------------------------
  194. 8. Execute the remaining branches of the code.  Enter the following
  195.    commands from the Shell, ignoring the output:
  196.  
  197.       test  -1
  198.       test   1
  199.       test 101
  200.  
  201. ------------------------------------------------------------
  202. 9. Run the cover utility one more time:
  203.  
  204.       cover
  205.  
  206.    You should see the following output:
  207.    
  208.       In file test.c
  209.                              37 Lines,        0 not executed
  210.       In file test2.c
  211.                               9 Lines,        0 not executed
  212.   
  213.  
  214. ------------------------------------------------------------
  215. 10. Examine the results in test.cov:
  216.  
  217.        se test.cov
  218.  
  219.     No remaining lines have arrows.  The "test suite" you just executed exercises
  220.     all lines of the program.
  221.  
  222. Notice that the file "cover.dat" reflects all tests run, not just the most
  223. recent one.  If you want the data to reflect only the most recently run
  224. test, rename or delete the file "cover.dat" before running the test.
  225.  
  226.