INSTALLING GCT USING ANONYMOUS FTP Brian Marick Testing Foundations Documentation for version 1.4 of GCT. Document version 1.3 This document describes how to fetch the Generic Coverage Tool (GCT) via anonymous FTP, then install it. _1. _A_d_v_e_r_t_i_s_i_n_g, _M_a_i_l_i_n_g _L_i_s_t, _a_n_d _D_i_s_c_l_a_i_m_e_r_s In addition to GCT, I provide (1) GCT support, training, and Expansion Kits. (2) on-site training courses in testing (3) custom toolsmithing and consulting. You can reach me at Brian Marick Testing Foundations 809 Balboa Champaign, Ill. 61820 (217) 351-7228 marick@cs.uiuc.edu, testing!marick@uunet.uu.net There is a GCT mailing list: gct@cs.uiuc.edu. To join the list, send mail to gct-request@cs.uiuc.edu. 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. 9 9 _2. _I_n_s_t_a_l_l_a_t_i_o_n Please read the entire document before starting; it may save you confusion. If you discover a bug, whether in this docu- ment or GCT, please see the "Reporting Bugs" section at the end. If you only want to evaluate GCT, skip the steps marked with (*). Do the basic installation, try the demonstration described in _A _T_u_t_o_r_i_a_l _I_n_t_r_o_d_u_c_t_i_o_n _t_o _G_C_T, then come back and finish the installation. _2._1. _M_a_k_e _a _d_i_r_e_c_t_o_r_y _f_o_r _t_h_e _s_o_u_r_c_e The name is unimportant. "gct" is a good choice. In the rest of the document, this directory will be called . You will need roughly 33,000 1K blocks during the installa- tion process. If you don't install and execute the tests, you'll save about 17,000 blocks. The final executables will require roughly 3000 1K blocks. _2._2. _F_e_t_c_h _t_h_e _f_i_l_e_s FTP to cs.uiuc.edu. Login is "anonymous", password is your email address. Change to the directory pub/testing/gct.files. The directory will contain at least these files: src.tar.Z You need this. tests.tar.Z This is the complete GCT test suite. A small installa- tion test suite is bundled with the source, so you don't need this. However, it's wise to run the full test suite if you're installing on what might be a new type of machine. doc.ps.tar.Z Formatted Postscript versions of all the documents, including manpages. doc.txt.tar.Z Formatted plain-text versions of all the documents, including manpages. doc.src.tar.Z The nroff source for the documents. Most use the -ms macro set. One uses the -me macro set. You must fetch this file if you want online manpages. 9 9 You may also see files like src.patch.1 doc.patch.1 and so on. These are bug fixes and minor enhancements that do not justify an entirely new release. See the file PATCHES in the directory for a description of the patches. See the patch(1) manpage to find out how to apply patches. (If there is no patch(1) on your system, you can get it from various anonymous FTP repositories.) Finally, you may see files like notes.machinename These are files that describe how to port GCT to particular machines. They were supplied by users after the release. Decide what files you need and fetch them. Remember to use "binary mode" when fetching files ending in ".Z". Place all the files in the directory you created. _2._3. _U_n_p_a_c_k _t_h_e _f_i_l_e_s First, unpack the source by typing % zcat src.tar.Z | tar xf - (The "%" represents your prompt.) If you see error messages like src/: cannot create and you're on System V, use "tar xof" instead of "tar xf". Unpack the other files ending in ".Z" the same way. If you desire, install patches, following the instructions in the PATCHES file. _2._4. _S_e_l_e_c_t _i_n_s_t_a_l_l_a_t_i_o_n _d_i_r_e_c_t_o_r_i_e_s Change to the /src directory and edit the file named "Makefile". (1) Change the macro called "bindir" to be the directory where you want the executables to go. You must use a full pathname (beginning with a "/"). (2) Change the macro called "libdir" to be the directory where you want libraries and GCT's C preprocessor to go. You must use a full pathname. (3) Change the macro called "mandir" to be the directory where you want manpages to go. Also change "manext" to be the same as the last letter of "mandir". (4) glist is a user-contributed program that annotates a source listing with coverage information. It requires the freeware Perl program. Change the macro called "perlexec" to be the location of Perl on your system. If you do not have Perl, set "perlexec" to NOPERL. GCT doesn't require Perl, so all you'll lose is the ability to print pretty Postscript listings. If you use A4 paper (common in Europe), glist requires one further change: edit glist.src to redefine page_top to be 839 and page_right_edge to be 595. (5) By default, the makefile installs the programs and manual pages using "cp". On BSD-derived systems, you may want to change the "INSTALL" macro to "install -c". On some System V systems, you may want to use "cpset". If you strip the executables, you could save upwards of a megabyte of disk space. (6) A useful GNU emacs utility, gedit.el, is by default installed in $(libdir). You may want to install it with other local emacs utilities. Search for "gedit.el" in the Makefile and change what you find. _2._5. _I_d_e_n_t_i_f_y _t_h_e _d_e_f_a_u_l_t _c_o_m_p_i_l_e_r GCT works by preprocessing C source files, instrumenting (rewriting) the C code, then passing the instrumented code along to a compiler ("cc" by default). To preprocess correctly, GCT must know what type of C compiler "cc" is. In the Makefile, change the "gctscript" macro to one of these values: gct-ansi if "cc" is an ANSI C compiler. gct-trad if "cc" is a traditional "Kernighan and Ritchie" C com- piler. gct-gcc if "cc" is the GNU C compiler (version 1 and - on most systems - also version 2). gct-gcc2 if "cc" is a version 2 GNU C compiler (applies only to some systems - try this only if "gct-gcc" doesn't work). 9 9 All of these selections are simple shell scripts that invoke the true executable, gct.exec, appropriately. The one you chose will be installed as "$(bindir)/gct". If you're not sure what type of compiler you have, use the default - users will quickly correct you if it makes a difference, and installing another script later is simple. If the default compiler is named something other than "cc", edit the script to pass the -test-cc argument to "gct.exec". For example, if your ANSI C compiler is "xcc", you'd edit "gct-ansi" to read: gct.exec -test-cc xcc "$@" Comments in the scripts give more details. _2._6. _C_o_n_f_i_g_u_r_e _f_o_r _y_o_u_r _m_a_c_h_i_n_e (1) Look in /src/config.notes. It describes special-case installation procedures for particular systems. (2) Configure the system for your machine type and operat- ing system. This is done by typing % config.gcc TYPE in the /src directory. The types are listed in the file called INSTALL. These include "sun4-os4" for Sparc systems running SunOS 4.x, "rs6000" for RS/6000s running AIX, and "hp-parisc" for the HP Precision Architecture machines running HP-UX. If your machine is not in the INSTALL list, see the Troubleshooting section at the end of this document. _2._7. _M_a_k_e _G_C_T Type % make _2._8. (*) _R_u_n _t_h_e _t_e_s_t_s Type % cd testdir % ./run standard The tests take a long time to run, probably more than an hour. As each test runs, it will log results. If a test logs nothing but its name, it succeeded. A portion of a suc- cessful log looks like this: == branch/ ==== quest ==== if ==== switch ==== switch2 ==== switch3 You may also run the weak mutation test suite by typing % ./run weak Note, however, that programs instrumented for weak mutation tend to be a challenge to older C compilers, so you may see spurious failures. The tests may also be in error; it's easy to write unportable weak mutation tests. Please report any failures you see, and I'll tell you if they're a real problem. _2._9. _I_n_s_t_a_l_l _G_C_T If you are satisfied with the results of the tests, return to the /gct/src directory. Check that the installa- tion directory is in your search path ($PATH). Then type % make install To install the manpages, type % make man_install The manpages are in the doc.src tar file, so this won't work if you didn't extract that. _2._1_0. (*) _C_h_e_c_k _f_o_r _f_u_r_t_h_e_r _c_o_m_p_i_l_e_r _d_e_p_e_n_d_e_n_c_i_e_s Head off a possible compiler-dependent problem that shows up when processing functions that take a variable number of arguments. Make sure that the directory where you installed the GCT executables is in your $PATH, then type % ./check-varargs gct You should see "Normal" function arguments (integers, doubles, and pointers) work. Structure arguments to functions work. Coverage results are correct. SUCCESS If the program does not report success, see the Troubleshooting section at the end of this document. _2._1_1. _T_e_s_t _t_h_e _I_n_s_t_a_l_l_a_t_i_o_n Run the installation test suite. It checks that GCT was installed correctly and that it seems to be working. You can run the installation tests even if you didn't fetch the entire test suite. % cd testdir % ./run install You should see lines like this: == installed/ == multiple-dir/ == demo/ ==== basic-gsummary ==== basic-greport ==== basic-all _2._1_2. _P_r_i_n_t _t_h_e _D_o_c_u_m_e_n_t_a_t_i_o_n These documents are delivered with GCT: A Tutorial Introduction to GCT (tutorial) Generic Coverage Tool (GCT) User's Guide (user) GCT Troubleshooting (trouble) Using Race Coverage with GCT (race) Using Weak Mutation Coverage with GCT (weak) The manual pages (manpages) (1) If you fetched the doc.ps.tar.Z file, the documents are all in /doc/postscript. Each document is in a file whose basename is the parenthesized word above, with extension ".ps". (That is, the tutorial is in /doc/postscript/tutorial.ps.) (2) If you fetched the doc.txt.tar.Z file, the documents are in /doc/plaintext. The documents all end in ".txt". (3) If you fetched the source, documents are in subdirec- tories of /doc. Each document's directory has the name given in parentheses above. Before formatting, look at the file /doc/include/Make.tmpl. The source for this document is in /doc/install. It's not included in the postscript or plaintext direc- tories. _2._1_3. (*) _C_o_n_f_i_g_u_r_e _o_t_h_e_r _c_o_m_p_i_l_e_r_s You may want to use other compilers with GCT. It is con- venient to set these up now. You need to do two things: (1) Create a shell script that causes GCT to invoke the right compiler. (2) Make sure that GCT preprocesses files correctly for that compiler. Any user can do the first step, but only someone with privileges can correct any problems found in the second step. _2._1_3._1. (*) _S_e_l_e_c_t_i_n_g _a _c_o_m_p_i_l_e_r You earlier selected one of "gct-ansi", "gct-trad", "gct- gcc", or "gct-gcc2" as the interface to the default C com- piler. You can use these as templates for scripts that invoke other C compilers. (1) Copy one of those scripts to a file you can edit, con- ventionally named "gct-COMPILER-NAME". (If you're using version 2 of the GNU C compiler, try gct-gcc before gct-gcc2.) (2) Edit the script to pass the "-test-cc" argument to "gct.exec". For example, "gct-gcc-1.40" might contain this line: gct.exec -D__GNUC__ -test-cc gcc-1.40 "$@" (3) Edit the makefile and edit the "install" and "unin- stall" targets to install and uninstall your new script. Comments in those targets give examples. _2._1_3._2. (*) _C_h_e_c_k_i_n_g _t_h_e _c_o_m_p_i_l_e_r Type % make install % ./check-varargs gct-COMPILER-NAME using the compiler you just added instead of "COMPILER- NAME". If check-varargs does not report success, see the Troubleshooting section. _2._1_4. (*) _C_l_e_a_n _u_p Type % make clean % (cd testdir; make clean) _3. _T_r_o_u_b_l_e_s_h_o_o_t_i_n_g _3._1. _M_a_c_h_i_n_e _n_o_t _i_n _I_N_S_T_A_L_L _f_i_l_e If your system is not listed in INSTALL, try a similar sys- tem. GCT's configuration files are those of the GNU C com- piler. GCT actually uses very little of that configuration information. So, one configuration file is often as good as another, if they both describe roughly the same version of UNIX. For example, the configuration file for a VAX running BSD Unix can be used to produce a GCT for a Sun 3 running SunOS 3 (though there is also a sun3-os3 configuration file). For an example, see xm-rs6000.h and tm-rs6000.h (both in /src/config). You'll see that 68000 configuration information is actually used. When you get GCT working, tell me what what you did so that other users may benefit. _3._2. _T_e_s_t _s_c_r_i_p_t_s _d_o _n_o_t _r_u_n If your machine's copy of /bin/sh doesn't support shell functions, the test suite will fail. There are still a few machines out there with old versions of the shell. There is no easy solution to this problem. If you have the Korn shell, you can replace #!/bin/sh with #!/bin/ksh in all the _r_u_n scripts in all the tests (or at least in the installa- tion tests). _3._3. _F_a_i_l_u_r_e_s _i_n _g_s_u_m_m_a_r_y _t_e_s_t_s If you see failures in the tools/gsummary/levels tests and the gsummary tests under system/mult-newinst-3, the cause is likely a configuration problem. Are 'char' types unsigned on your machine? If so, you must add a line like this to "config.h". /* Need to extend chars for regex.c. */ #define SIGN_EXTEND_CHAR(c) ((((int) (c)) << 24) >> 24) 9 9 If GNU emacs runs on your machine, you can look in the GNU Emacs "m-" file for an appropriate definition. If bytes are not 8 bits wide on your machine, you'll need to add something like #define BYTEWIDTH 16 (I'll be surprised if you don't have many more problems.) After editing config.h, remove regex.o and remake. _3._4. _c_h_e_c_k-_v_a_r_a_r_g_s _c_a_u_s_e_s _G_C_T _t_o _d_u_m_p _c_o_r_e In some cases, GCT's reaction to a syntax error is to print an error message and then later dump core. This is because the original GCT design assumed that it would be given only syntactically correct programs; this assumption lingers on in some places. The configuration problems that check-varargs detects mani- fest themselves as syntax errors, and they may cause core dumps. The core dumps are irrelevant; they will go away when you fix the underlying configuration problem. See the next section. _3._5. _c_h_e_c_k-_v_a_r_a_r_g_s _f_a_i_l_s Programs that use #include or #include can cause problems that "check-varargs" detects. There are two related causes that have two separate solutions. _3._5._1. _C_o_m_p_i_l_e_r-_s_p_e_c_i_f_i_c _d_e_f_i_n_i_t_i_o_n_s Variable-length argument lists are implemented through the standard C macros va_start(), va_arg(), and va_end(), defined in /usr/include/varargs.h and /usr/include/stdarg.h. (The former file is for traditional C programs; the latter for ANSI-compliant programs.) These macros are sometimes of the form #ifdef DEFINITION_PREDEFINED_BY_THE_SYSTEM_SUPPLIED_C_COMPILER #define va_arg(list, mode) ... something that works... #else #define va_arg(list, mode) ... something that doesn't work... #endif For example, on Sun 4 systems, va_arg() is defined incorrectly unless __BUILTIN_VA_ARG_INCR is defined. To fix this problem, (1) Examine /usr/include/varargs.h or /usr/include/stdarg.h to discover what the #defines are. (2) Edit the /src/tm.h file (this is a symbolic link to the /src/config/tm-*.h file for your machine). (3) Add the necessary #defines to CPP_PREDEFINES. (4) Remake GCT. (5) Mail what you did to me so I can include it in the standard distribution. (I've already done this for sun4-os4.) _3._5._2. _C_o_m_p_i_l_e_r-_s_p_e_c_i_f_i_c _i_n_c_l_u_d_e _f_i_l_e_s Certain compilers, such as the GNU C compiler, don't use /usr/include/varargs.h or /usr/include/stdarg.h when they see #include or #include Instead, they use files in a "hidden" location. (Usually, "/bin/cc" will use the files in /usr/include, but sometimes this program is really the GNU C compiler, in which case it will sometimes use a hidden directory.) You earlier edited the makefile to define the "$(libdir)" directory. That directory now contains another directory, "gct-include", which contains entries for each compiler on the system. Each entry is a symbolic link pointing to a directory where a particular C compiler's include files are stored. For example: The default compiler's include files are pointed to by $(libdir)/gct-include/default. If this link does not exist (and it normally doesn't), the compiler's include files are assumed to be in /usr/include. If "gcc" is the GNU C compiler's name, invoking GCT as 9 9 gct.exec -test-cc gcc does more than tell GCT to use "gcc" to compile the instrumented source. It also tells GCT to use $(libdir)/gct-include/gcc to find gcc-specific include files for preprocessing. If there is no such directory, /usr/include is used instead. Therefore, if you use % ./check-varargs gct-gcc and it reports problems, you can fix them by typing some- thing like this: % ln -s $(GCC_INCLUDE) $(libdir)/gct-include/gcc Replace $(libdir) with whatever you used in the makefile and $(GCC_INCLUDE) with the appropriate directory on your machine. On my machine, that would be /local/lib/gnu/gcc-include or /local/lib/gnu/gcc-lib/sparc-sunos4.1/2.1/include If your machine does not support symbolic links, make the gct-include entry a directory and copy the compiler's include files there. (It might be OK just to copy stdarg.h and varargs.h, but it's probably safest to copy everything.) _3._6. _M_a_k_i_n_g _G_C_T: _c_a_n_n_o_t _l_o_a_d _c_o_m_m_a_n_d '_b_i_s_o_n' If the tar file was unpacked and then the source was copied to another directory or another machine, the makefile may fail with a message like "Cannot load command 'bison'". Two C files, cexp.c and c-parse.tab.c, are created using the BISON parser-generator. The original source files are cexp.y and c-parse.y. In the tar file, the C files are newer than the Y files, so that the makefile doesn't attempt to recreate them. If you copy the GCT sources around, the dates on the files will change, and the makefile may attempt to recreate the C files from the Y files. Unless you have BISON on your system, the make will fail. The solution is to touch the C files after the copy: % cp -r * $destdir % cd $destdir % touch cexp.c c-parse.tab.c % make 9 9 _4. _R_e_p_o_r_t_i_n_g _B_u_g_s I can spend only a limited amount of time on unpaid GCT sup- port. Please help me spend that time productively by making your bug reports as useful as possible. Send installation bug reports to me (marick@cs.uiuc.edu) instead of to the mailing list. For a bug in the documentation, include the document version number and GCT version number (both of these are on the title page). For a software or installation bug, please do the following: (1) Tell me what machine and version of UNIX you're using. What argument was given to config.gcc? (2) Tell me what version of GCT you're installing. (If GCT was built, you can find that out by typing `gct -v'.) Tell me if you installed any patches. (3) What value of $(gctscript) did you use in the makefile? Did you modify that file? (4) Send me a log of what failed. I need to see what you did, and what the result was. If the failure is in a test suite, it's enough to send me a few lines before the failure (so I can identify the failing test) and all the failure output. (5) Describe what is wrong with the log (even if it's obvi- ous). (6) Include your email address in the body of the bug report. (7) Put your phone number in the bug report, in case return mail to you fails. 9 9