<commit_before>%% $Id$

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\documentclass[english]{article}
\usepackage[latin1]{inputenc}
\usepackage{babel}
\usepackage{verbatim}

%% do we have the `hyperref package?
\IfFileExists{hyperref.sty}{
   \usepackage[bookmarksopen,bookmarksnumbered]{hyperref}
}{}

%% do we have the `fancyhdr' or `fancyheadings' package?
\IfFileExists{fancyhdr.sty}{
\usepackage[fancyhdr]{latex2man}
}{
\IfFileExists{fancyheadings.sty}{
\usepackage[fancy]{latex2man}
}{
\usepackage[nofancy]{latex2man}
\message{no fancyhdr or fancyheadings package present, discard it}
}}

%% do we have the `rcsinfo' package?
\IfFileExists{rcsinfo.sty}{
\usepackage[nofancy]{rcsinfo}
\rcsInfo $Id$
\setDate{\rcsInfoLongDate}
}{
\setDate{ 2008/07/09}
\message{package rcsinfo not present, discard it}
}

\setVersionWord{Version:}  %%% that's the default, no need to set it.
\setVersion{=PACKAGE_VERSION=}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{document}

\begin{Name}{1}{hpcstruct}{The HPCToolkit Performance Tools}{The HPCToolkit Performance Tools}{hpcstruct:\\ Recovery of Static Program Structure}

\Prog{hpcstruct} recovers the static program structure of \emph{fully optimized} object code for use with an \textbf{HPCToolkit} correlation tool.
In particular, \Prog{hpcstruct}, recovers source code procedures and loop nests, detects inlining, and associates procedures and loops with object code addresses.
See \HTMLhref{hpctoolkit.html}{\Cmd{hpctoolkit}{1}} for an overview of \textbf{HPCToolkit}.

\end{Name}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Synopsis}

\Prog{hpcstruct} \oOpt{options} \Arg{binary}

Typical usage:\\
\Prog{hpcstruct} \Arg{binary} > \Arg{output.psxml}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Description}

Given an application binary or DSO \Arg{binary}, \Prog{hpcstruct} recovers the program structure of its object code and writes to standard output a program structure to object code mapping.
\Prog{hpcstruct} is designed primarily for highly optimized binaries created from C, C++ and Fortran source code.
Because \Prog{hpcstruct}'s algorithms exploit a binary's debugging information, for best results, \Arg{binary} should be compiled with standard debugging information.
\Prog{hpcstruct}'s output is typically passed to \textbf{HPCToolkit}'s correlation tool, \HTMLhref{hpcprof.html}{\Cmd{hpcprof}{1}} or \HTMLhref{hpcprof-flat.html}{\Cmd{hpcprof-flat}{1}}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Arguments}

\begin{Description}
\item[\Arg{binary}] An executable binary or dynamically linked library.
Note that \Prog{hpcstruct} does not recover program structure for libraries that \Arg{binary} depends on.  To create such information, run hpcstruct on each dynamically linked library (or relink your program with static versions of the libraries).
\end{Description}

Default values for an option's optional arguments are shown in \{\}.

\subsection{Options: General}

\begin{Description}
\item[\OptoArg{-v}{n}, \OptoArg{--verbose}{n}]
Verbose: generate progress messages to stderr at verbosity level \Arg{n}.  \{1\}

\item[\Opt{-V}, \Opt{--version}]
Print version information.

\item[\Opt{-h}, \Opt{--help}]
Print help.

\item[\OptoArg{--debug}{n}]
Debug: use debug level \Arg{n}. \{1\}

\item[\OptArg{--debug-proc}{glob}]
Debug structure recovery for procedures matching the procedure glob \Arg{glob}.
\end{Description}

\subsection{Options: Recovery and Output}

\begin{Description}
  \item[\Opt{-i}, \Opt{--irreducible-interval-as-loop-off}] Do not treat irreducible intervals as loops.
  \item[\Opt{-f}, \Opt{--forward-substitution-off}] Assume that forward substitution does not occur.  (Useful for handling erroneous PGI debugging info.)

  \item[\OptArg{-p}{path-list}, \OptArg{--canonical-paths}{path-list}] Ensure that scope tree only contains files found in the colon-separated path list \Arg{path-list}. May be passed multiple times.

\item[\Opt{-n}, \Opt{--normalize-off}] Turn off scope tree normalization.
\item[\Opt{-u}, \Opt{--unsafe-normalize-off}] Turn off potentially unsafe normalization.

\item[\Opt{-c}, \Opt{--compact}] Generate compact output, eliminating extra white space.
\end{Description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Examples}

%\begin{enumerate}
%\item 
Assume we have collected profiling information for the (optimized) binary \File{sweep3dsingle}, compiled with debugging information.
We wish to recover program structure in the file \File{sweep3dsingle.psxml} for use with \HTMLhref{hpcprof.html}{\Cmd{hpcprof}{1}} or \HTMLhref{hpcprof-flat.html}{\Cmd{hpcprof-flat}{1}}.
To do this, execute:
\begin{verbatim}
    hpcstruct sweep3dsingle > sweep3dsingle.psxml
\end{verbatim}

%\end{enumerate}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Notes}

\begin{enumerate}

\item For best results, an application binary should be compiled with debugging information.
To generate debugging information while also enabling optimizations, use the appropriate variant of \verb+-g+ for the following compilers:
\begin{itemize}
\item GNU, Intel and PathScale compilers: \verb+-g+
\item PGI compilers: \verb+-gopt+
\item Compaq and SGI MIPSpro compilers: \verb+-g3+
\item Sun Compilers: \verb+-g -xs+
\end{itemize}

\item While \Prog{hpcstruct} attempts to guard against inaccurate debugging information, some compilers (notably PGI's) often generate invalid and inconsistent debugging information.
Garbage in; garbage out.

\item C++ mangling is compiler specific. On non-GNU platforms, \Prog{hpcstruct}
tries both platform's and GNU's demangler.

\end{enumerate}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Bugs}

\begin{enumerate}

\item \Prog{hpcstruct} may incorrectly infer the structure of loops contained within switch statements.
When reconstructing the control flow graph (CFG) of the object code, \Prog{hpcstruct} currently ignores indirect jumps and does not add edges from the jump to possible target basic blocks.
The result is an incomplete CFG and a misleading loop nesting tree.
The workaround is to use an if/elseif/else statement.

\end{enumerate}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{See Also}

\HTMLhref{hpctoolkit.html}{\Cmd{hpctoolkit}{1}}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Version}

Version: \Version\ of \Date.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{License and Copyright}

\begin{description}
\item[Copyright] \copyright\ 2002-2008, Rice University.
\item[License] See \File{README.License}.
\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Authors}

\noindent
<NAME> \\
<NAME> \\
<NAME> \\
Email: \Email{<EMAIL>} \\
WWW: \URL{http://hipersoft.cs.rice.edu/hpctoolkit}.

Thanks to <NAME> and <NAME>.

\LatexManEnd

\end{document}

%% Local Variables:
%% eval: (add-hook 'write-file-hooks 'time-stamp)
%% time-stamp-start: "setDate{ "
%% time-stamp-format: "%:y/%02m/%02d"
%% time-stamp-end: "}\n"
%% time-stamp-line-limit: 50
%% End:

<commit_msg>Update hpcstruct's compiler notes.<commit_after>%% $Id$

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\documentclass[english]{article}
\usepackage[latin1]{inputenc}
\usepackage{babel}
\usepackage{verbatim}

%% do we have the `hyperref package?
\IfFileExists{hyperref.sty}{
   \usepackage[bookmarksopen,bookmarksnumbered]{hyperref}
}{}

%% do we have the `fancyhdr' or `fancyheadings' package?
\IfFileExists{fancyhdr.sty}{
\usepackage[fancyhdr]{latex2man}
}{
\IfFileExists{fancyheadings.sty}{
\usepackage[fancy]{latex2man}
}{
\usepackage[nofancy]{latex2man}
\message{no fancyhdr or fancyheadings package present, discard it}
}}

%% do we have the `rcsinfo' package?
\IfFileExists{rcsinfo.sty}{
\usepackage[nofancy]{rcsinfo}
\rcsInfo $Id$
\setDate{\rcsInfoLongDate}
}{
\setDate{ 2008/09/20}
\message{package rcsinfo not present, discard it}
}

\setVersionWord{Version:}  %%% that's the default, no need to set it.
\setVersion{=PACKAGE_VERSION=}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{document}

\begin{Name}{1}{hpcstruct}{The HPCToolkit Performance Tools}{The HPCToolkit Performance Tools}{hpcstruct:\\ Recovery of Static Program Structure}

\Prog{hpcstruct} recovers the static program structure of \emph{fully optimized} object code for use with an \textbf{HPCToolkit} correlation tool.
In particular, \Prog{hpcstruct}, recovers source code procedures and loop nests, detects inlining, and associates procedures and loops with object code addresses.
See \HTMLhref{hpctoolkit.html}{\Cmd{hpctoolkit}{1}} for an overview of \textbf{HPCToolkit}.

\end{Name}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Synopsis}

\Prog{hpcstruct} \oOpt{options} \Arg{binary}

Typical usage:\\
\Prog{hpcstruct} \Arg{binary} > \Arg{output.psxml}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Description}

Given an application binary or DSO \Arg{binary}, \Prog{hpcstruct} recovers the program structure of its object code and writes to standard output a program structure to object code mapping.
\Prog{hpcstruct} is designed primarily for highly optimized binaries created from C, C++ and Fortran source code.
Because \Prog{hpcstruct}'s algorithms exploit a binary's debugging information, for best results, \Arg{binary} should be compiled with standard debugging information.
\Prog{hpcstruct}'s output is typically passed to \textbf{HPCToolkit}'s correlation tool, \HTMLhref{hpcprof.html}{\Cmd{hpcprof}{1}} or \HTMLhref{hpcprof-flat.html}{\Cmd{hpcprof-flat}{1}}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Arguments}

\begin{Description}
\item[\Arg{binary}] An executable binary or dynamically linked library.
Note that \Prog{hpcstruct} does not recover program structure for libraries that \Arg{binary} depends on.  To create such information, run hpcstruct on each dynamically linked library (or relink your program with static versions of the libraries).
\end{Description}

Default values for an option's optional arguments are shown in \{\}.

\subsection{Options: General}

\begin{Description}
\item[\OptoArg{-v}{n}, \OptoArg{--verbose}{n}]
Verbose: generate progress messages to stderr at verbosity level \Arg{n}.  \{1\}

\item[\Opt{-V}, \Opt{--version}]
Print version information.

\item[\Opt{-h}, \Opt{--help}]
Print help.

\item[\OptoArg{--debug}{n}]
Debug: use debug level \Arg{n}. \{1\}

\item[\OptArg{--debug-proc}{glob}]
Debug structure recovery for procedures matching the procedure glob \Arg{glob}.
\end{Description}

\subsection{Options: Recovery and Output}

\begin{Description}
  \item[\Opt{-i}, \Opt{--irreducible-interval-as-loop-off}] Do not treat irreducible intervals as loops.
  \item[\Opt{-f}, \Opt{--forward-substitution-off}] Assume that forward substitution does not occur.  (Useful for handling erroneous PGI debugging info.)

  \item[\OptArg{-p}{path-list}, \OptArg{--canonical-paths}{path-list}] Ensure that scope tree only contains files found in the colon-separated path list \Arg{path-list}. May be passed multiple times.

\item[\Opt{-n}, \Opt{--normalize-off}] Turn off scope tree normalization.
\item[\Opt{-u}, \Opt{--unsafe-normalize-off}] Turn off potentially unsafe normalization.

\item[\Opt{-c}, \Opt{--compact}] Generate compact output, eliminating extra white space.
\end{Description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Examples}

%\begin{enumerate}
%\item 
Assume we have collected profiling information for the (optimized) binary \File{sweep3dsingle}, compiled with debugging information.
We wish to recover program structure in the file \File{sweep3dsingle.psxml} for use with \HTMLhref{hpcprof.html}{\Cmd{hpcprof}{1}} or \HTMLhref{hpcprof-flat.html}{\Cmd{hpcprof-flat}{1}}.
To do this, execute:
\begin{verbatim}
    hpcstruct sweep3dsingle > sweep3dsingle.psxml
\end{verbatim}

%\end{enumerate}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Notes}

\begin{enumerate}

\item For best results, an application binary should be compiled with debugging information.
To generate debugging information while also enabling optimizations, use the appropriate variant of \verb+-g+ for the following compilers:
\begin{itemize}
\item GNU compilers: \verb+-g+
\item Intel compilers: \verb+-g -debug inline_debug_info+
\item PathScale compilers: \verb+-g+
\item PGI compilers: \verb+-gopt+
%\item Compaq and SGI MIPSpro compilers: \verb+-g3+
%\item Sun Compilers: \verb+-g -xs+
\end{itemize}

\item While \Prog{hpcstruct} attempts to guard against inaccurate debugging information, some compilers (notably PGI's) often generate invalid and inconsistent debugging information.
Garbage in; garbage out.

\item C++ mangling is compiler specific. On non-GNU platforms, \Prog{hpcstruct}
tries both platform's and GNU's demangler.

\end{enumerate}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Bugs}

\begin{enumerate}

\item \Prog{hpcstruct} may incorrectly infer the structure of loops contained within switch statements.
When reconstructing the control flow graph (CFG) of the object code, \Prog{hpcstruct} currently ignores indirect jumps and does not add edges from the jump to possible target basic blocks.
The result is an incomplete CFG and a misleading loop nesting tree.
The workaround is to use an if/elseif/else statement.

\end{enumerate}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{See Also}

\HTMLhref{hpctoolkit.html}{\Cmd{hpctoolkit}{1}}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Version}

Version: \Version\ of \Date.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{License and Copyright}

\begin{description}
\item[Copyright] \copyright\ 2002-2008, Rice University.
\item[License] See \File{README.License}.
\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Authors}

\noindent
<NAME> \\
<NAME> \\
<NAME> \\
Email: \Email{<EMAIL>} \\
WWW: \URL{http://hipersoft.cs.rice.edu/hpctoolkit}.

Thanks to <NAME> and <NAME>.

\LatexManEnd

\end{document}

%% Local Variables:
%% eval: (add-hook 'write-file-hooks 'time-stamp)
%% time-stamp-start: "setDate{ "
%% time-stamp-format: "%:y/%02m/%02d"
%% time-stamp-end: "}\n"
%% time-stamp-line-limit: 50
%% End:


{'fraction_non_alphanumeric': 0.24052740227741892, 'fraction_numerical': 0.005327295731504295, 'mean_word_length': 5.943134535367545, 'pattern_counts': {'":': 0, '<': 15, '<?xml version=': 0, '>': 19, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 6}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3787946', 'n_tokens_mistral': 4559, 'n_tokens_neox': 4244, 'n_words': 1300}