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 % secret!
  28 %\item[\tr{-caf-all}:]
  29 %\index{-caf-all option}
  30 %The costs of all CAFs in a module are usually attributed to one
  31 %``big'' CAF cost-centre. With this option, all CAFs get their own cost-centre.
  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 %Alternative profiling semantics have also been implemented. To use
  57 %these the runtime system and prelude libraries must have been built
  58 %for the alternative profiling setup. This is done using a particular
  59 %UserWay setup. If your system has this been built for this profiling
  60 %system the alternative profiling system will normally be invoked using
  61 %the options:
  62 %\begin{description}
  63 %\item[\tr{-lex}:]
  64 %\index{-eval option}
  65 %for lexical profiling.
  66 %\item[\tr{-eval}:]
  67 %\index{-eval option}
  68 %for evaluation profiling.
  69 %\end{description}
  70 %All modules must be consistently compiled with the \tr{-lex} or
  71 %\tr{-eval} option instead of the \tr{-prof} option. The other
  72 %profiling options are still applicable.
  73 %
  74 %Finally we note that the options which dump the program source during
  75 %compilation may be useful to determine exactly what code is being
  76 %profiled. Useful options are:
  77 %\begin{description}
  78 %\item[\tr{-ddump-ds}:] dump after desugaring. Any automatic \tr{_scc_}
  79 %annotations will have been added.
  80 %\item[\tr{-ddump-simpl}:] dump after simplification.
  81 %\item[\tr{-ddump-stg}:] dump the STG-code immediately before code
  82 %generation.
  83 %\end{description}
  84