This is the mail archive of the binutils@sources.redhat.com mailing list for the binutils project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

[RFA]: Generate gprof.1 man page


Hi!

To finish with the man page generation from .texinfo files,
the following patch implements this for gprof.

Can you integrate this patch ?

	Stephane

2001-03-31  Stephane Carrez  <Stephane.Carrez@worldnet.fr>

	* gprof.texi: Put @c man begin and @c man end indications
	to generate man page using texi2pod and pod2man.  Added SEEALSO,
	SYNOPSIS, BUGS, FILES and DESCRIPTION from original gprof.1
	enclosed in @ifset man condition.
	* Makefile.am (MANCONF, TEXI2POD, POD2MAN): New variable.
	Generate gprof.1 from gprof.texi.
	* gprof.1: Generate from gprof.texi.
	* Makefile.in: Regenerate.
Index: Makefile.am
===================================================================
RCS file: /cvs/src/src/gprof/Makefile.am,v
retrieving revision 1.8
diff -u -p -r1.8 Makefile.am
--- Makefile.am	2001/02/27 06:43:55	1.8
+++ Makefile.am	2001/03/31 16:28:59
@@ -49,8 +49,26 @@ po/POTFILES.in: @MAINT@ Makefile
 	for file in $(POTFILES); do echo $$file; done | sort > tmp \
 	  && mv tmp $(srcdir)/po/POTFILES.in
 
+MANCONF  = -Dman
+
+TEXI2POD = perl $(srcdir)/../etc/texi2pod.pl
+
+POD2MAN = pod2man --center="GNU" --release="binutils-$(VERSION)" --section=1
+
 info_TEXINFOS = gprof.texi
 man_MANS = gprof.1
+
+# Build the man page from the texinfo file
+# The sed command removes the no-adjust Nroff command so that
+# the man output looks standard.
+$(srcdir)/gprof.1: $(srcdir)/gprof.texi
+	touch $(srcdir)/gprof.1
+	-$(TEXI2POD) $(MANCONF) -Dgprof < $(srcdir)/gprof.texi > gprof.pod
+	-($(POD2MAN) gprof.pod | \
+		sed -e '/^.if n .na/d' > $(srcdir)/gprof.1.T$$$$ && \
+		mv -f $(srcdir)/gprof.1.T$$$$ $(srcdir)/gprof.1) || \
+		(rm -f $(srcdir)/gprof.1.T$$$$ && exit 1)
+	rm -f gprof.pod
 
 # Targets to rebuild dependencies in this Makefile.
 # Have to get rid of DEP1 here so that "$?" later includes all sources.
Index: gprof.texi
===================================================================
RCS file: /cvs/src/src/gprof/gprof.texi,v
retrieving revision 1.6
diff -u -p -r1.6 gprof.texi
--- gprof.texi	2001/03/13 21:07:29	1.6
+++ gprof.texi	2001/03/31 16:29:20
@@ -1,6 +1,6 @@
 \input texinfo @c -*-texinfo-*-
 @setfilename gprof.info
-@c Copyright 1988, 1992, 1993, 1998, 1999, 2000
+@c Copyright 1988, 1992, 1993, 1998, 1999, 2000, 2001
 @c Free Software Foundation, Inc.
 @settitle GNU gprof
 @setchapternewpage odd
@@ -18,14 +18,17 @@ END-INFO-DIR-ENTRY
 @ifinfo
 This file documents the gprof profiler of the GNU system.
 
-Copyright (C) 1988, 92, 97, 98, 99, 2000 Free Software Foundation, Inc.
+@c man begin COPYRIGHT
+Copyright (C) 1988, 92, 97, 98, 99, 2000, 2001 Free Software Foundation, Inc.
 
-      Permission is granted to copy, distribute and/or modify this document
-      under the terms of the GNU Free Documentation License, Version 1.1
-      or any later version published by the Free Software Foundation;
-      with no Invariant Sections, with no Front-Cover Texts, and with no
-      Back-Cover Texts.  A copy of the license is included in the
-      section entitled "GNU Free Documentation License".
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1
+or any later version published by the Free Software Foundation;
+with no Invariant Sections, with no Front-Cover Texts, and with no
+Back-Cover Texts.  A copy of the license is included in the
+section entitled "GNU Free Documentation License".
+
+@c man end
 
 @ignore
 Permission is granted to process this file through Tex and print the
@@ -96,6 +99,102 @@ section entitled "GNU Free Documentation
 @node Introduction
 @chapter Introduction to Profiling
 
+@ifset man
+@c man title gprof display call graph profile data
+
+@smallexample
+@c man begin SYNOPSIS
+gprof [ -[abcDhilLsTvwxyz] ] [ -[ACeEfFJnNOpPqQZ][@var{name}] ] 
+ [ -I @var{dirs} ] [ -d[@var{num}] ] [ -k @var{from/to} ]
+ [ -m @var{min-count} ] [ -t @var{table-length} ]
+ [ --[no-]annotated-source[=@var{name}] ] 
+ [ --[no-]exec-counts[=@var{name}] ]
+ [ --[no-]flat-profile[=@var{name}] ] [ --[no-]graph[=@var{name}] ]
+ [ --[no-]time=@var{name}] [ --all-lines ] [ --brief ] 
+ [ --debug[=@var{level}] ] [ --function-ordering ] 
+ [ --file-ordering ] [ --directory-path=@var{dirs} ]
+ [ --display-unused-functions ] [ --file-format=@var{name} ]
+ [ --file-info ] [ --help ] [ --line ] [ --min-count=@var{n} ]
+ [ --no-static ] [ --print-path ] [ --separate-files ]
+ [ --static-call-graph ] [ --sum ] [ --table-length=@var{len} ]
+ [ --traditional ] [ --version ] [ --width=@var{n} ]
+ [ --ignore-non-functions ] [ --demangle[=@var{STYLE}] ]
+ [ --no-demangle ] [ @var{image-file} ] [ @var{profile-file} @dots{} ]
+@c man end
+@end smallexample
+
+@c man begin DESCRIPTION
+@code{gprof} produces an execution profile of C, Pascal, or Fortran77 
+programs.  The effect of called routines is incorporated in the profile 
+of each caller.  The profile data is taken from the call graph profile file
+(@file{gmon.out} default) which is created by programs
+that are compiled with the @samp{-pg} option of
+@code{cc}, @code{pc}, and @code{f77}.
+The @samp{-pg} option also links in versions of the library routines
+that are compiled for profiling.  @code{Gprof} reads the given object 
+file (the default is @code{a.out}) and establishes the relation between
+its symbol table and the call graph profile from @file{gmon.out}.
+If more than one profile file is specified, the @code{gprof}
+output shows the sum of the profile information in the given profile files.
+
+@code{Gprof} calculates the amount of time spent in each routine.
+Next, these times are propagated along the edges of the call graph.
+Cycles are discovered, and calls into a cycle are made to share the time
+of the cycle.
+
+@c man end
+
+@c man begin BUGS
+The granularity of the sampling is shown, but remains
+statistical at best.
+We assume that the time for each execution of a function
+can be expressed by the total time for the function divided
+by the number of times the function is called.
+Thus the time propagated along the call graph arcs to the function's
+parents is directly proportional to the number of times that
+arc is traversed.
+
+Parents that are not themselves profiled will have the time of
+their profiled children propagated to them, but they will appear
+to be spontaneously invoked in the call graph listing, and will
+not have their time propagated further.
+Similarly, signal catchers, even though profiled, will appear
+to be spontaneous (although for more obscure reasons).
+Any profiled children of signal catchers should have their times
+propagated properly, unless the signal catcher was invoked during
+the execution of the profiling routine, in which case all is lost.
+
+The profiled program must call @code{exit}(2)
+or return normally for the profiling information to be saved
+in the @file{gmon.out} file.
+@c man end
+
+@c man begin FILES
+@table @code
+@item @file{a.out}
+the namelist and text space.
+@item @file{gmon.out}
+dynamic call graph and profile.
+@item @file{gmon.sum}
+summarized dynamic call graph and profile.  
+@end table
+@c man end
+
+@c man begin SEEALSO
+monitor(3), profil(2), cc(1), prof(1), and the Info entry for @file{gprof}.
+
+``An Execution Profiler for Modular Programs'',
+by S. Graham, P. Kessler, M. McKusick;
+Software - Practice and Experience,
+Vol. 13, pp. 671-685, 1983.
+
+``gprof: A Call Graph Execution Profiler'',
+by S. Graham, P. Kessler, M. McKusick;
+Proceedings of the SIGPLAN '82 Symposium on Compiler Construction,
+SIGPLAN Notices, Vol. 17, No  6, pp. 120-126, June 1982.
+@c man end
+@end ifset
+
 Profiling allows you to learn where your program spent its time and which
 functions called which other functions while it was executing.  This
 information can show you which pieces of your program are slower than you
@@ -129,6 +228,8 @@ You must run @code{gprof} to analyze the
 
 The next three chapters explain these steps in greater detail.
 
+@c man begin DESCRIPTION
+
 Several forms of output are available from the analysis.
 
 The @dfn{flat profile} shows how much time your program spent in each function,
@@ -145,6 +246,7 @@ lot of time.  @xref{Call Graph}.
 The @dfn{annotated source} listing is a copy of the program's
 source code, labeled with the number of times each line of the
 program was executed.  @xref{Annotated Source}.
+@c man end
 
 To better understand how profiling works, you may wish to read
 a description of its implementation.
@@ -297,6 +399,7 @@ The order of these options does not matt
 @node Output Options,Analysis Options,,Invoking
 @section Output Options
 
+@c man begin OPTIONS
 These options specify which of several output formats
 @code{gprof} should produce.
 
@@ -634,6 +737,8 @@ may be given; only one @var{function_nam
 @samp{-F} option.  The @samp{-F} option overrides the @samp{-E} option.
 
 @end table
+
+@c man end
 
 Note that only one function can be specified with each @code{-e},
 @code{-E}, @code{-f} or @code{-F} option.  To specify more than one

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]