Short instructions how to "profile" (analyze time and memory usage)
your Castle Game Engine applications.
====

Most of this description actually applies to any program
compiled using FPC, not just Castle Game Engine.

This document is just a shortcut. Your real guide is
the documentation of FPC and Valgrind and Valgrind/Callgrind manual :

- http://valgrind.org/docs/manual/cl-manual.html

- http://wiki.lazarus.freepascal.org/Profiling

------------------------------------------------------------------------------
Compile for valgrind:

- Make sure you use proper options when compiling with FPC.

  - If you use our build tool for compilation
    ( https://github.com/castle-engine/castle-engine/wiki/Build-Tool )
    then just use --mode=valgrind command-line option.
    This will pass correct options to FPC underneath.

  - Otherwise, make sure:
    - You MUST use -gv option, this adds stuff necessary for valgrind.
    - You SHOULD use -gl (line info) to get line number information.
    - You SHOULD NOT use -Xs (strip debug info), it would strip useful
      function info from your exe.

  - If you compile from command-line using direct "fpc ..." command
    and "@castle-fpc.cfg", then search in ../castle-fpc.cfg for
    valgrind options and uncomment them.
    Be sure to also comment out -Xs inside.

  - Otherwise, just add
    -gv
    -gl
    to your ~/.fpc.cfg. Remember to remove them later.

  - Be sure that you don't strip symbols.
    If you use castle-fpc.cfg to compile, comment out -Xs option inside.

- Clean units (to recompile all for valgrind), like
    make clean
  in CGE directory. Otherwise, you will not get profiling info inside CGE
  routines.

- Compile your project as usual. Compile a release version (with -dRELEASE),
  you want to profile released code (otherwise you may find
  serious time eaters in stuff like range or overflow checking,
  and they will skew your results).

------------------------------------------------------------------------------
For speed profiling:

Use valgrind's callgrind tool.
Running program through callgrind adds an enormous slowdown,
especially with instrumentation (this is when actual measurements take place).
So it's advised to start without instrumentation, and only turn it on
for the interested code part.

valgrind --tool=callgrind --instr-atstart=no ./my-program

# from other shell:
callgrind_control -i on
callgrind_control -i off

# investigate the report:
kcachegrind

------------------------------------------------------------------------------
For memory usage profiling:

- Use valgrind's massif tool.
  Compile like described previously for callgrind (with -gv), then run like

    valgrind --tool=massif --run-libc-freeres=no ./my-program

  There are some more useful Valgrind options,
  we have them in massif_fpc script in
  https://github.com/castle-engine/cge-scripts/blob/master/massif_fpc .
  So just get https://raw.githubusercontent.com/castle-engine/cge-scripts/master/massif_fpc ,
  place it in your $PATH, and then execute

    massif_fpc ./my-program

  Afterwards investigate the resulting massif.out.xxx file, by

    ms_print massif.out.xxx
