diff options
| -rw-r--r-- | gnu/egcs/gcc/Makefile.bsd-wrapper | 4 | ||||
| -rw-r--r-- | gnu/egcs/gcc/gcov.1 | 479 | ||||
| -rw-r--r-- | gnu/usr.bin/cvs/Makefile.bsd-wrapper | 4 | ||||
| -rw-r--r-- | gnu/usr.bin/cvs/man/rcs2log.1 | 99 | ||||
| -rw-r--r-- | gnu/usr.bin/texinfo/Makefile.bsd-wrapper | 6 |
5 files changed, 585 insertions, 7 deletions
diff --git a/gnu/egcs/gcc/Makefile.bsd-wrapper b/gnu/egcs/gcc/Makefile.bsd-wrapper index b3532b539cc..d59da274d7e 100644 --- a/gnu/egcs/gcc/Makefile.bsd-wrapper +++ b/gnu/egcs/gcc/Makefile.bsd-wrapper @@ -1,6 +1,6 @@ -# $OpenBSD: Makefile.bsd-wrapper,v 1.13 2003/02/16 17:07:22 deraadt Exp $ +# $OpenBSD: Makefile.bsd-wrapper,v 1.14 2003/02/16 18:28:40 deraadt Exp $ -MAN= cccp.1 gcc.1 gcc-local.1 protoize.1 +MAN= cccp.1 gcc.1 gcc-local.1 protoize.1 gcov.1 MLINKS+= gcc.1 cc.1 MLINKS+= cccp.1 cpp.1 MLINKS+= protoize.1 unprotoize.1 diff --git a/gnu/egcs/gcc/gcov.1 b/gnu/egcs/gcc/gcov.1 new file mode 100644 index 00000000000..8bf5a2072cc --- /dev/null +++ b/gnu/egcs/gcc/gcov.1 @@ -0,0 +1,479 @@ +.\" +.\" Published by the Free Software Foundation 59 Temple Place - Suite 330 +.\" Boston, MA 02111-1307 USA +.\" +.\" Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, +.\" 1999, 2000 Free Software Foundation, Inc. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of +.\" this manual under the conditions for verbatim copying, provided also +.\" that the sections entitled "GNU General Public License" and "Funding +.\" for Free Software" are included exactly as in the original, and +.\" provided that the entire resulting derived work is distributed under +.\" the terms of a permission notice identical to this one. +.\" +.\" Permission is granted to copy and distribute translations of this +.\" manual into another language, under the above conditions for modified +.\" versions, except that the sections entitled "GNU General Public +.\" License" and "Funding for Free Software", and this permission notice, +.\" may be included in translations approved by the Free Software Foundation +.\" instead of in the original English. +.\" +.Dd February 15, 2003 +.Dt GCOV 1 +.Os +.Sh NAME +.Nm gcov +.Nd test coverage program +.Sh SYNOPSIS +.Nm +.Op Fl b +.Op Fl v +.Op Fl n +.Op Fl l +.Op Fl f +.Op Fl o Ar directory +.Ar sourcefile +.Sh DESCRIPTION +The +.Nm +utility is a test coverage program. +Use it in concert with +.Xr gcc 1 +to analyze programs to help create more efficient, faster running +code. +.Nm +can be used as a profiling tool to help discover where optimization efforts +will best affect the code. +.Nm +can also be used along with the other profiling tool +.Xr gprof 1 , +to assess which parts of the code use the greatest amount of computing time. +.Pp +Profiling tools help analyze the code's performance. +Using a profiler such as +.Nm gcov +or +.Xr gprof 1 , +basic performance statistics can be obtained, such as: +.Pp +.Bl -bullet -compact +.It +how often each line of code executes +.It +what lines of code are actually executed +.It +how much computing time each section of code uses +.El +.Pp +Once you know these things about how your code works when compiled, +you can look at each module to see which modules should be optimized. +.Nm +helps determine where to work on optimization. +.Pp +Software developers also use coverage testing in concert with +testsuites, to make sure software is actually good enough for a release. +Testsuites can verify that a program works as expected; +a coverage program tests to see how much of the program is exercised by the +testsuite. +Developers can then determine what kinds of test cases need +to be added to the testsuites to create both better testing and a better +final product. +.Pp +Code should be compiled without optimization when using +.Nm +because the optimization, by combining some lines of code into +one function, +may not give as much information as necesary to look +for `hot spots' where the code is using a great deal of computer time. +Likewise, because +.Nm +accumulates statistics by line (at the lowest resolution), +it works best with a programming style that places only +one statement on each line. +If complicated macros that expand to loops or to other control structures +are used, the statistics are less helpful - they only report on the line +where the macro call appears. +If complex macros behave like functions, they can be replaced with +inline functions to solve this problem. +.Pp +.Nm +creates a logfile called +.Sq Ar sourcefile Ns Li .gcov +which indicates how many times each line of a source file +.Sq Ar sourcefile Ns Li \&.c +has executed. +These logfiles can then be used along with +.Xr gprof 1 +to aid in fine-tuning the performance of the programs. +.Xr gprof 1 +gives timing information which can be used along with the information you +obtained from +.Nm gcov . +.Pp +.Nm +works only on code compiled with GNU CC. +It is not compatible with any other profiling or test coverage mechanism. +.Pp +.Nm +accepts the following options: +.Pp +.Bl -tag -width Ds +.It Fl b +Write branch frequencies to the output file, and write branch +summary info to the standard output. +This option indicates how often each branch in the program was taken. +.It Fl v +Display the +.Nm +version number (on the standard error stream). +.It Fl n +Do not create the +.Nm +output file. +.It Fl l +Create long file names for included source files. +For example, if the header file +.Pa x.h +contains code, and was included in the file +.Pa a.c , +then running +.Nm +on the file +.Pa a.c +will produce an output file called +.Pa a.c.x.h.gcov +instead of +.Pa x.h.gcov . +This can be useful if +.Pa x.h +is included in multiple source files. +.It Fl f +Output summaries for each function in addition to the file level summary. +.It Fl o Ar directory +The directory where the object files live. +.Nm +will search for +.Pa .bb , .bbg , +and +.Pa .da +files in this directory. +.El +.Pp +When using +.Nm gcov , +programs must first be compiled with two special GNU CC options: +.Fl fprofile-arcs ftest-coverage . +This tells the compiler to generate additional information needed by +.Nm +(basically a flow graph of the program) +and also includes additional code in the object files for generating the +extra profiling information needed by +.Nm gcov . +These additional files are placed in the directory where the source code +is located. +.Pp +Running the program will cause profile output to be generated. +For each source file compiled with +.Fl fprofile-arcs , +an accompanying +.Pa .da +file will be placed in the source directory. +.Pp +Running +.Nm +with the program's source file names as arguments +will now produce a listing of the code along with frequency of execution +for each line. +For example, if the program is called +.Pa tmp.c , +this is what is displayed when using the basic +.Nm +facility: +.Pp + $ gcc -fprofile-arcs -ftest-coverage tmp.c + $ a.out + $ gcov tmp.c + 87.50% of 8 source lines executed in file tmp.c + Creating tmp.c.gcov. +.Pp +The file +.Pa tmp.c.gcov +contains output from +.Nm gcov . +Here is a sample: +.Pp + main() + { + 1 int i, total; + + 1 total = 0; + + 11 for (i = 0; i < 10; i++) + 10 total += i; + + 1 if (total != 45) + ###### printf ("Failure\\n"); + else + 1 printf ("Success\\n"); + 1 } +.Pp +When the +.Fl b +option is used, output looks like this: +.Pp + $ gcov -b tmp.c + 87.50% of 8 source lines executed in file tmp.c + 80.00% of 5 branches executed in file tmp.c + 80.00% of 5 branches taken at least once in file tmp.c + 50.00% of 2 calls executed in file tmp.c + Creating tmp.c.gcov. +.Pp +Here is a sample of a resulting +.Pa tmp.c.gcov +file: +.Pp + main() + { + 1 int i, total; + + 1 total = 0; + + 11 for (i = 0; i < 10; i++) + branch 0 taken = 91% + branch 1 taken = 100% + branch 2 taken = 100% + 10 total += i; + + 1 if (total != 45) + branch 0 taken = 100% + ###### printf ("Failure\\n"); + call 0 never executed + branch 1 never executed + else + 1 printf ("Success\\n"); + call 0 returns = 100% + 1 } +.Pp +For each basic block, a line is printed after the last line of the +basic block describing the branch or call that ends the basic block. +There can be multiple branches and calls listed for a single source +line if there are multiple basic blocks that end on that line. +In this case, the branches and calls are each given a number. +There is no simple way to map these branches and calls back to source +constructs. +In general, though, the lowest numbered branch or call will correspond +to the leftmost construct on the source line. +.Pp +For a branch, if it was executed at least once, then a percentage +indicating the number of times the branch was taken divided by the +number of times the branch was executed will be printed. +Otherwise, the message "never executed" is printed. +.Pp +For a call, if it was executed at least once, then a percentage +indicating the number of times the call returned divided by the number +of times the call was executed will be printed. +This will usually be 100%, +but may be less for functions which call `exit' or `longjmp', +and thus may not return everytime they are called. +.Pp +The execution counts are cumulative. +If the example program were executed again without removing the +.Pa .da +file, +the count for the number of times each line in the source was executed +would be added to the results of the previous run(s). +This is potentially useful in several ways. +For example, it could be used to accumulate data over a +number of program runs as part of a test verification suite, +or to provide more accurate long-term information over a large number of +program runs. +.Pp +The data in the +.Pa .da +files is saved immediately before the program exits. +For each source file compiled with +.Fl fprofile-arcs , +the profiling code first attempts to read in an existing +.Pa .da +file; +if the file doesn't match the executable +(differing number of basic block counts) +it will ignore the contents of the file. +It then adds in the new execution counts and finally writes the data +to the file. +.Pp +.Sh USING GCOV WITH GCC OPTIMIZATION +.Pp +If +.Nm +is to be used to help optimize code, +programs must be compiled with two special GNU CC options: +.Fl fprofile-arcs ftest-coverage . +Aside from that, any other GNU CC options can be used; +but if you want to prove that every single line in your +program was executed, you should not compile with optimization at the +same time. +On some machines the optimizer can eliminate some simple +code lines by combining them with other lines. +For example, code like this: +.Pp + if (a != b) + c = 1; + else + c = 0; +.Pp +can be compiled into one instruction on some machines. +In this case, there is no way for +.Nm +to calculate separate execution counts for each line because there +isn't separate code for each line. +Hence the +.Nm +output looks like this if the program is compiled with optimization: +.Pp + 100 if (a != b) + 100 c = 1; + 100 else + 100 c = 0; +.Pp +The output shows that this block of code, combined by optimization, +executed 100 times. +In one sense this result is correct, +because there was only one instruction representing all four of these lines. +However, the output does not indicate how many times the result was 0 and how +many times the result was 1. +.Pp +.Sh BRIEF DESCRIPTION OF GCOV DATA FILES +.Pp +.Nm +uses three files for doing profiling. +The names of these files are derived from the original _source_ file +by substituting the file suffix with either +.Pa .bb , .bbg , +or +.Pa .da . +All of these files are placed in the same directory as the source file, +and contain data stored in a platform-independent method. +.Pp +The +.Pa .bb +and +.Pa .bbg +files are generated when the source file is compiled with the GNU CC +.Fl ftest-coverage +option. +The +.Pa .bb +file contains a list of source files (including headers), +functions within those files, +and line numbers corresponding to each basic block in the source file. +.Pp +The +.Pa .bb +file format consists of several lists of 4-byte integers +which correspond to the line numbers of each basic block in the file. +Each list is terminated by a line number of 0. +A line number of -1 is used to designate that the source file name +(padded to a 4-byte boundary and followed by another -1) follows. +In addition, a line number of -2 is used to designate that the name of a +function (also padded to a 4-byte boundary and followed by a -2) follows. +.Pp +The +.Pa .bbg +file is used to reconstruct the program flow graph for the source file. +It contains a list of the program flow arcs +(possible branches taken from one basic block to another) +for each function which, +in combination with the +.Pa .bb +file, +enables +.Nm +to reconstruct the program flow. +.Pp +In the +.Pa .bbg +file, the format is: +.Pp + number of basic blocks for function #0 (4-byte number) +.br + total number of arcs for function #0 (4-byte number) +.br + count of arcs in basic block #0 (4-byte number) +.br + destination basic block of arc #0 (4-byte number) +.br + flag bits (4-byte number) +.br + destination basic block of arc #1 (4-byte number) +.br + flag bits (4-byte number) +.br + ... +.br + destination basic block of arc #N (4-byte number) +.br + flag bits (4-byte number) +.br + count of arcs in basic block #1 (4-byte number) +.br + destination basic block of arc #0 (4-byte number) +.br + flag bits (4-byte number) +.br + ... +.Pp +A -1 (stored as a 4-byte number) is used to separate each function's +list of basic blocks, and to verify that the file has been read +correctly. +.Pp +The +.Pa .da +file is generated when a program containing object files +built with the GNU CC +.Fl fprofile-arcs +option is executed. +A separate +.Pa .da +file is created for each source file compiled with this option, +and the name of the +.Pa .da +file is stored as an absolute pathname in the resulting object file. +This path name is derived from the source file name by substituting a +.Pa .da +suffix. +.Pp +The format of the +.Pa .da +file is fairly simple. +The first 8-byte number is the number of counts in the file, +followed by the counts +(stored as 8-byte numbers). +Each count corresponds to the number of +times each arc in the program is executed. +The counts are cumulative; +each time the program is executed, it attemps to combine the existing +.Pa .da +files with the new counts for this invocation of the program. +It ignores the contents of any +.Pa .da +files whose number of arcs doesn't +correspond to the current program, +and merely overwrites them instead. +.Pp +All three of these files use the functions in +.Pa gcov-io.h +to store integers; +the functions in this header provide a machine-independent +mechanism for storing and retrieving data from a stream. +.Sh SEE ALSO +.Xr gcc 1 +.Xr gprof 1 +.Sh HISTORY +This man page describes version 1.5 of +.Nm gcov . diff --git a/gnu/usr.bin/cvs/Makefile.bsd-wrapper b/gnu/usr.bin/cvs/Makefile.bsd-wrapper index 5271a7b189a..71faec287ed 100644 --- a/gnu/usr.bin/cvs/Makefile.bsd-wrapper +++ b/gnu/usr.bin/cvs/Makefile.bsd-wrapper @@ -1,8 +1,8 @@ -# $OpenBSD: Makefile.bsd-wrapper,v 1.41 2002/06/03 15:59:38 todd Exp $ +# $OpenBSD: Makefile.bsd-wrapper,v 1.42 2003/02/16 18:28:41 deraadt Exp $ .include <bsd.own.mk> -MAN= man/cvs.1 man/cvs.5 man/cvsbug.8 +MAN= man/cvs.1 man/cvs.5 man/cvsbug.8 man/rcs2log.1 GNUCFLAGS= CC="${CC}" CFLAGS="${CFLAGS} ${COPTS}" CLEANFILES= src/version.c lib/getdate.c lib/getdate.h macintosh/Makefile \ os2/Makefile zlib/Makefile \ diff --git a/gnu/usr.bin/cvs/man/rcs2log.1 b/gnu/usr.bin/cvs/man/rcs2log.1 new file mode 100644 index 00000000000..bffbc553894 --- /dev/null +++ b/gnu/usr.bin/cvs/man/rcs2log.1 @@ -0,0 +1,99 @@ +.\" +.\" Copyright 1992, 93, 94, 95, 96, 97, 1998 Free Software Foundation, Inc. +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2, or (at your option) +.\" any later version. +.\" +.\" This program 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. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with this program; see the file COPYING. If not, write to the +.\" Free Software Foundation, Inc., 59 Temple Place - Suite 330, +.\" Boston, MA 02111-1307, USA. +.\" +.Dd February 15, 2003 +.Dt RCS2LOG 1 +.Os +.Sh NAME +.Nm rcs2log +.Nd RCS to ChangeLog generator +.Sh SYNOPSIS +.Nm rcs2log +.Bk -words +.Op Fl c Ar changelog +.Op Fl h Ar hostname +.Op Fl i Ar indent +.Op Fl l Ar length +.Op Fl R +.Op Fl r Ar option +.Op Fl t Ar tabwidth +.Op Fl u Ar login<TAB>fullname<TAB>mailaddr +.Op Fl v +.Op Fl -help +.Op Fl -version +.Op Ar file ... +.Ek +.Sh DESCRIPTION +The +.Nm +utility generates a change log prefix from RCS files (perhaps in the CVS +repository) and the ChangeLog (if any). +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl c Ar changelog +Output a change log prefix to +.Ar changelog +(default ChangeLog). +.It Fl h Ar hostname +Use +.Ar hostname +in change log entries (default current host). +.It Fl i Ar indent +Indent change log lines by +.Ar indent +spaces (default 8). +.It Fl l Ar length +Try to limit log lines to +.Ar length +characters (default 79). +.It Fl R +If no +.Ar file Ns Li (s) +are given and RCS is used, recurse through working directory. +.It Fl r Ar option +Pass +.Ar option +to subsidiary log command. +.It Fl t Ar tabwidth +Tab stops are every +.Ar tabwidth +characters (default 8). +.It Fl u Ar "login<TAB>fullname<TAB>mailaddr" +Assume +.Ar login +has +.Ar fullname +and +.Ar mailaddr . +.It Fl v +Append RCS revision to file names in log lines. +.It Fl -help +Output help. +.It Fl -version +Output version number. +.El +.Sh SEE ALSO +.Xr rcs 1 , +.Xr rcsintro 1 , +.Xr rlog 1 , +.Xr rcsfile 5 +.Sh AUTHORS +Paul Eggert <eggert@twinsun.com> +.Sh BUGS +Report bugs to <bug-gnu-emacs@gnu.org>. diff --git a/gnu/usr.bin/texinfo/Makefile.bsd-wrapper b/gnu/usr.bin/texinfo/Makefile.bsd-wrapper index 74230e31ea8..74066156c2f 100644 --- a/gnu/usr.bin/texinfo/Makefile.bsd-wrapper +++ b/gnu/usr.bin/texinfo/Makefile.bsd-wrapper @@ -1,10 +1,10 @@ -# $OpenBSD: Makefile.bsd-wrapper,v 1.36 2002/06/11 22:37:14 art Exp $ +# $OpenBSD: Makefile.bsd-wrapper,v 1.37 2003/02/16 18:28:41 deraadt Exp $ INFODIR= infodir=/usr/share/info INFOPATH= DEFAULT_INFOPATH=/usr/local/info:/usr/share/info:. -MAN= doc/info.1 doc/install-info.1 doc/makeinfo.1 doc/texi2dvi.1 -MAN+= doc/texindex.1 doc/info.5 doc/texinfo.5 +MAN= doc/info.1 doc/install-info.1 doc/makeinfo.1 doc/texi2dvi.1 +MAN+= doc/texindex.1 doc/info.5 doc/texinfo.5 doc/infokey.1 GNUCFLAGS= CC="${CC}" CFLAGS="${CFLAGS} ${COPTS}" \ ACLOCAL=true AUTOHEADER=true AUTOCONF=true AUTOMAKE=true |