ghc/docs/users_guide/prof-compiler-options.lit

   1 %
   2 % Included by  prof-options.lit  and  how_to_run.lit
   3 %
   4
   5 To make use of the cost centre profiling system {\em all} modules must
   6 be compiled and linked with the \tr{-prof} option.\index{-prof option}
   7 Any \tr{_scc_} constructs you've put in your source will spring to life.
   8
   9 Without a \tr{-prof} option, your \tr{_scc_}s are ignored; so you can
  10 compiled \tr{_scc_}-laden code without changing it.
  11
  12 There are a few other profiling-related compilation options.  Use them
  13 {\em in addition to} \tr{-prof}.  These do not have to be used
  14 consistently for all modules in a program.
  15
  16 \begin{description}
  17 \item[\tr{-auto}:]
  18 \index{-auto option}
  19 GHC will automatically add \tr{_scc_} constructs for
  20 all top-level, exported functions.
  21
  22 \item[\tr{-auto-all}:]
  23 \index{-auto-all option}
  24 {\em All} top-level functions, exported or not, will be automatically
  25 \tr{_scc_}'d.
  26
  27 \item[\tr{-caf-all}:]
  28 \index{-caf-all option}
  29 The costs of all CAFs in a module are usually attributed to one
  30 ``big'' CAF cost-centre. With this option, all CAFs get their own cost-centre.
  31 An ``if all else fails'' option...
  32
  33 %\item[\tr{-dict-all}:]
  34 %\index{-dict-all option}
  35 %Similarly, this option means that all ``dictionaries'' (internal
  36 %constructs to support Haskell overloading) should get their own
  37 %cost-centre.  (Again, the costs are usually attributed to one ``big''
  38 %DICT cost-centre.)
  39 %
  40 %Incidentally, something is probably Bad Wrong (i.e., a GHC bug) if you
  41 %see big costs attributed to dictionaries.
  42
  43 \item[\tr{-ignore-scc}:]
  44 \index{-ignore-scc option}
  45 Ignore any \tr{_scc_} constructs,
  46 so a module which already has \tr{_scc_}s can be
  47 compiled for profiling with the annotations ignored.
  48
  49 \item[\tr{-G<group>}:]
  50 \index{-G<group> option}
  51 Specifies the \pl{<group>} to be attached to all the cost-centres
  52 declared in the module. If no group is specified it defaults to the
  53 module name.
  54 \end{description}
  55
  56 In addition to the \tr{-prof} option your system might be setup to
  57 enable you to compile and link with the \tr{-prof-details}
  58 \index{\tr{-prof-details option}} option instead. This enables
  59 additional detailed counts to be reported with the \tr{-P} RTS option.
  60 %-prof-details should also enable age profiling if we get it going again ...
  61
  62 %Alternative profiling semantics have also been implemented. To use
  63 %these the runtime system and prelude libraries must have been built
  64 %for the alternative profiling setup. This is done using a particular
  65 %UserWay setup. If your system has this been built for this profiling
  66 %system the alternative profiling system will normally be invoked using
  67 %the options:
  68 %\begin{description}
  69 %\item[\tr{-lex}:]
  70 %\index{-eval option}
  71 %for lexical profiling.
  72 %\item[\tr{-eval}:]
  73 %\index{-eval option}
  74 %for evaluation profiling.
  75 %\end{description}
  76 %All modules must be consistently compiled with the \tr{-lex} or
  77 %\tr{-eval} option instead of the \tr{-prof} option. The other
  78 %profiling options are still applicable.
  79 %
  80 %Finally we note that the options which dump the program source during
  81 %compilation may be useful to determine exactly what code is being
  82 %profiled. Useful options are:
  83 %\begin{description}
  84 %\item[\tr{-ddump-ds}:] dump after desugaring. Any automatic \tr{_scc_}
  85 %annotations will have been added.
  86 %\item[\tr{-ddump-simpl}:] dump after simplification.
  87 %\item[\tr{-ddump-stg}:] dump the STG-code immediately before code
  88 %generation.
  89 %\end{description}
  90