[goodguy/cin-manual-latex.git] / parts / Developer.tex

\chapter{Developer's Section}%
\label{cha:Developer's_Section}

\section{How Builds Really Work and Even More Options}
\label{sec:How Builds Really Work and Even More Options}

This section describes how builds really work if you want to know more about making changes or understanding the process; probably only for a developer or system administrator.
\medskip

Builds occur in 4 basic steps:
\smallskip
\begin{enumerate}[nosep]
        \item unpack/patch source code
        \item configure build
        \item make build targets
        \item installation
\end{enumerate}

So, an example of what happens in 4 steps for a single-user build would be as follows:
\smallskip

\begin{enumerate}[nosep]
        \item unpack/patch source code\newline
        git clone --depth 1 ``git:/{\dots}/target'' cinelerra5\newline
        ./autogen.sh
        \item configure build\newline
        ./configure --with-single-user
        \item make build targets\newline
        make 2{\textgreater}\&1 {\textbar} tee log
        \item installation\newline
        make install
\end{enumerate}
\medskip

A lot of things can be tweaked to change the results. \ Mostly these changes are parameters to the configure step, which can change important build related items, like the application name, or where and what the target system directories should be. \ This makes it possible to have several versions at the same time on the same computer if needed. \ To see what it is that the makefiles use to build Cinelerra, look at the resulting top-level global\_config file which is created by the ./configure step.
\medskip

Building Cinelerra requires many thirdparty libraries, and it is recommended that you use the static build version included in the git repo. \ Some of them are patched, and fix significant bugs. \ It is important to note that because system installation historically has been with as many shared objects as possible, the defaults are that any system library detected during configuration setup will be used, when the package is built ``-{}-without-single-user'', which is the default build. \ To build with static thirdparty libraries for system install to the system /usr area, use:
\smallskip

\hspace{2em}.configure -{}-enable-static-build --prefix=/usr
\medskip

Sometimes, additional package parameters and variables are needed during thirdparty builds. \ These optional values occur before and after the ``configure'' and ``make'' commands during a build. \ A presentation of the format of the package qualified variable names and how they appear in the build procedure are:
\medskip

\hspace{2em}
\begin{tabular}{@{}ll}
        pkg.cfg\_vars & prepended to configure\\
        pkg.cfg\_params & appended to configure\\
        pkg.mak\_vars & prepended to make\\
        pkg.mak\_params & appended to make\\
    pkg.cflags & added as CFLAGS+=\$(cflags) to pkg.vars\\
        pkg.cppflags & added as CPPFLAGS+=\$(cppflags) to pkg.vars\\
\end{tabular}
\bigskip

These steps are done for EACH of the packages in the thirdparty build:
\smallskip

\hspace{2em}{\textless}pkg.cfg\_vars{\textgreater} ./configure {\textless}pkg.cfg\_params{\textgreater}

\hspace{2em}{\textless}pkg.mak\_vars{\textgreater} make {\textless}pkg.mak\_params{\textgreater}
\bigskip

The thirdparty Makefile has a set of default vars and params used to build each of the needed thirdparty packages, but you can specify new or overriding values for these Makefile substitutions. \ These thirdparty build config changes are specified in the top-level file: cin\_config. \ By using this file, you can save the configuration changes made for the current build to use the next time you do a new build. \ For example, to add an include file path to the giflib build, add this line to cin\_config:
\medskip

\hspace{2em}giflib.cflags := -I/usr/local/include/giflib5
\medskip

To have a param/var change apply to all thirdparty builds, use:
\medskip

\hspace{2em}CFG\_VARS, CFG\_PARAMS, MAK\_VARS, MAK\_PARAMS
\medskip

CFLAGS, CXXFLAGS and LDFLAGS are forwarded to the thirdparty build environment via:
\medskip

\hspace{2em}CFLAGS=-ggdb ./configure -{}-with-single-user
\medskip

However, there is no guarantee that the thirdparty build will honor the environmental flags.

Finally, there are build controls, which enable/disable and set build features.
\bigskip

A few of the more useful ./configure -{}-parameters are:
\smallskip

\hspace{2em}
\begin{tabular}{@{}ll}
        {}-{}-with-jobs=n & where n=number of build jobs; defaults to 1.5*cpus+2\\
        {}-{}-enable-static-build & build all 3rd party libs; defaults to yes if single-user, else no\\
        {}-{}-with-single-user& build installs to {\textless}build\_path{\textgreater}/bin; \ no system installation\\
\end{tabular}

\medskip

The ./configure command builds ``global\_config''. \ The global\_config is read by the thirdparty/Makefile to create the recipes and definitions used by the thirdparty build.
\medskip

There are a lot of different options.  Thirdparty library build control is available in the configure step of the build.  Thirdparty libraries are built on a demand basis.  So if you use:
\medskip

\hspace{2em}
\begin{tabular}{@{}ll}
  --enable-libname=auto & \# the static-build enable, or the lack of a system library causes a build\\
  --enable-libname=yes  &  \# this forces the thirdparty build\\
  --enable-libname=no   &  \# this forces no thirdparty build\\
\end{tabular}
\medskip

FFmpeg is a ``strongly connected component''in the build linkage and widely influences the Cinelerra library demands.  It is possible to make small additions to the ffmpeg configuration step using the environment variable FFMPEG\_EXTRA\_CFG.  For example, to eliminate the use of libvdpau (an nvidia support library) in the ffmpeg configuration step after you have determined that it is causing an error, use:

\begin{itemize}[label={},nosep]
        \item make clean
        \item autogen.sh
        \item export FFMPEG\_EXTRA\_CFG={\textquotedbl} -{}-disable-vdpau{\textquotedbl} 
        \item ./configure {\dots}
\end{itemize}
\medskip

Specific information on using the current ffmpeg GIT repository follows.  You have to supply the actual URL location of the ffmpeg git as you can see in this example ?bld.sh? script:
\medskip

\begin{lstlisting}[numbers=none]
#!/bin/bash\newline
() ./autogen.sh\newline
./configure --with-single-user --with-booby --with-git-ffmpeg=https://git.ffmpeg.org/ffmpeg.git
make && make install ) 2>1 | tee log
mv Makefile Makefile.cfg
cp Makefile.devel Makefile
\end{lstlisting}

Since the procedure for obtaining the latest ffmpeg version is not always kept up-to-date and the line numbers will always change, you may have to create that patch first. \ Generally those line numbers are only updated by a developer when a new stable version with worthwhile features is actually included in the Cinelerra build. FFmpeg is constantly changing and many times the git version is not as stable as desired.

\section{Configuration Features}
\label{sec:Configuration Features}

A listing of the current configuration features as of January 11, 2020:

\begingroup
    \fontsize{10pt}{12pt}\selectfont
\begin{verbatim}

`configure' configures cinelerra 5.1 to adapt to many kinds of systems.

Usage: ./configure [OPTION]... [VAR=VALUE]...

To assign environment variables (e.g., CC, CFLAGS...), specify them as
VAR=VALUE.  See below for descriptions of some of the useful variables.

Defaults for the options are specified in brackets.

Configuration:
  -h, --help              display this help and exit
      --help=short        display options specific to this package
      --help=recursive    display the short help of all the included packages
  -V, --version           display version information and exit
  -q, --quiet, --silent   do not print `checking ...' messages
      --cache-file=FILE   cache test results in FILE [disabled]
  -C, --config-cache      alias for `--cache-file=config.cache'
  -n, --no-create         do not create output files
      --srcdir=DIR        find the sources in DIR [configure dir or `..']

Installation directories:
  --prefix=PREFIX         install architecture-independent files in PREFIX
                          [/usr/local]
  --exec-prefix=EPREFIX   install architecture-dependent files in EPREFIX
                          [PREFIX]

By default, `make install' will install all the files in
`/usr/local/bin', `/usr/local/lib' etc.  You can specify
an installation prefix other than `/usr/local' using `--prefix',
for instance `--prefix=$HOME'.

For better control, use the options below.

Fine tuning of the installation directories:
  --bindir=DIR            user executables [EPREFIX/bin]
  --sbindir=DIR           system admin executables [EPREFIX/sbin]
  --libexecdir=DIR        program executables [EPREFIX/libexec]
  --sysconfdir=DIR        read-only single-machine data [PREFIX/etc]
  --sharedstatedir=DIR    modifiable architecture-independent data [PREFIX/com]
  --localstatedir=DIR     modifiable single-machine data [PREFIX/var]
  --libdir=DIR            object code libraries [EPREFIX/lib]
  --includedir=DIR        C header files [PREFIX/include]
  --oldincludedir=DIR     C header files for non-gcc [/usr/include]
  --datarootdir=DIR       read-only arch.-independent data root [PREFIX/share]
  --datadir=DIR           read-only architecture-independent data [DATAROOTDIR]
  --infodir=DIR           info documentation [DATAROOTDIR/info]
  --localedir=DIR         locale-dependent data [DATAROOTDIR/locale]
  --mandir=DIR            man documentation [DATAROOTDIR/man]
  --docdir=DIR            documentation root [DATAROOTDIR/doc/cinelerra]
  --htmldir=DIR           html documentation [DOCDIR]
  --dvidir=DIR            dvi documentation [DOCDIR]
  --pdfdir=DIR            pdf documentation [DOCDIR]
  --psdir=DIR             ps documentation [DOCDIR]

Program names:
  --program-prefix=PREFIX            prepend PREFIX to installed program names
  --program-suffix=SUFFIX            append SUFFIX to installed program names
  --program-transform-name=PROGRAM   run sed PROGRAM on installed program names

Optional Features:
  --disable-option-checking  ignore unrecognized --enable/--with options
  --disable-FEATURE       do not include FEATURE (same as --enable-FEATURE=no)
  --enable-FEATURE[=ARG]  include FEATURE [ARG=yes]
  --enable-silent-rules   less verbose build output (undo: "make V=1")
  --disable-silent-rules  verbose build output (undo: "make V=0")
  --enable-dependency-tracking
                          do not reject slow dependency extractors
  --disable-dependency-tracking
                          speeds up one-time build
  --enable-a52dec         build a52dec (yes)
  --enable-djbfft         build djbfft (yes)
  --enable-audiofile      build audiofile (no)
  --enable-encore         build encore (no)
  --enable-esound         build esound (no)
  --enable-ffmpeg         build ffmpeg (yes)
  --enable-fftw           build fftw (auto)
  --enable-flac           build flac (auto)
  --enable-giflib         build giflib (yes)
  --enable-ilmbase        build ilmbase (auto)
  --enable-lame           build lame (auto)
  --enable-libavc1394     build libavc1394 (auto)
  --enable-libraw1394     build libraw1394 (auto)
  --enable-libiec61883    build libiec61883 (auto)
  --enable-libdv          build libdv (auto)
  --enable-libjpeg        build libjpeg (auto)
  --enable-opus           build opus (auto)
  --enable-openjpeg       build openjpeg (auto)
  --enable-libogg         build libogg (auto)
  --enable-libsndfile     build libsndfile (auto)
  --enable-libtheora      build libtheora (auto)
  --enable-libuuid        build libuuid (yes)
  --enable-libvorbis      build libvorbis (auto)
  --enable-mjpegtools     build mjpegtools (yes)
  --enable-openexr        build openexr (auto)
  --enable-tiff           build tiff (auto)
  --enable-twolame        build twolame (auto)
  --enable-x264           build x264 (auto)
  --enable-x265           build x265 (auto)
  --enable-libvpx         build libvpx (auto)
  --enable-lv2            build lv2 (auto)
  --enable-sratom         build sratom (auto)
  --enable-serd           build serd (auto)
  --enable-sord           build sord (auto)
  --enable-lilv           build lilv (auto)
  --enable-suil           build suil (auto)
  --enable-libaom         build libaom (auto)
  --enable-dav1d          build dav1d (auto)
  --enable-libwebp        build libwebp (auto)
  --enable-ffnvcodec      build ffnvcodec (auto)
  --enable-static-build   build static ([auto])
  --enable-x264_hidepth   build x264 10bit ([no])
  --enable-x265_hidepth   build x265 10bit ([no])

Optional Packages:
  --with-PACKAGE[=ARG]    use PACKAGE [ARG=yes]
  --without-PACKAGE       do not use PACKAGE (same as --with-PACKAGE=no)
  --with-jobs             parallel build jobs (auto)
  --with-exec-name        binary executable name (cin)
  --with-single-user      to install cin in bin (no)
  --with-ladspa-build     build ladspa library (yes)
  --with-lv2              lv2 library support (yes)
  --with-cinlib           cinelerra library path (auto)
  --with-cindat           cinelerra share path (auto)
  --with-plugin-dir       plugin install dir (auto)
  --with-ladspa-dir       ladspa install dir (auto)
  --with-config-dir       .bcast config dir ($$HOME/.bcast5)
  --with-nested-dir       nested proxy dir ($$HOME/Videos)
  --with-browser          cin_browser path (firefox)
  --with-git-ffmpeg       git ffmpeg using url (no)
  --with-noelision        use noelision/libpthread (auto)
  --with-booby            window lock trace booby trap (no)
  --with-libzmpeg         build libzmpeg (yes)
  --with-commercial       enable commercial capture (yes)
  --with-thirdparty       use thirdparty build (yes)
  --with-shuttle          shuttle device (yes)
  --with-wintv            usb 2040:826d wintv device (yes)
  --with-x10tv            usb 0bc7:0004 X10 remote device (yes)
  --with-vaapi            video acceleration api (yes)
  --with-vdpau            video decode+presentation api for unix (yes)
  --with-nv               nvenc/nvdec ffnvcodec api (yes)
  --with-cuda             nv cuda plugins (auto)
  --with-clang            use clang instead of gcc/g++ (no)
  --with-gl               use opengl (auto)
  --with-oss              use OSS audio (auto)
  --with-xft              use libXft (auto)
  --with-alsa             use libasound/alsa (auto)
  --with-firewire         use firewire (auto)
  --with-dv               use dv (auto)
  --with-dvb              use dvb (auto)
  --with-video4linux2     use v4l2 (auto)
  --with-xxf86vm          use xf86vmode (auto)
  --with-esound           use esd (auto)
  --with-shuttle          shuttle dev support (auto)
  --with-shuttle_usb      use libusb-1.0 (auto)
  --with-lv2              use lv2 (auto)
  --with-cuda             build cuda plugins (auto)
  --with-dl               system has libdl (auto)
  --with-opencv           opencv=sys/sta/dyn,git/tar=url (auto)
  --with-numa             system has libnuma (auto)
  --with-openexr          use openexr (auto)

Some influential environment variables:
  CC          C compiler command
  CFLAGS      C compiler flags
  LDFLAGS     linker flags, e.g. -L<lib dir> if you have libraries in a
              nonstandard directory <lib dir>
  LIBS        libraries to pass to the linker, e.g. -l<library>
  CPPFLAGS    (Objective) C/C++ preprocessor flags, e.g. -I<include dir> if
              you have headers in a nonstandard directory <include dir>
  CCAS        assembler compiler command (defaults to CC)
  CCASFLAGS   assembler compiler flags (defaults to CFLAGS)
  CXX         C++ compiler command
  CXXFLAGS    C++ compiler flags

Use these variables to override the choices made by `configure' or to help
it to find libraries and programs with nonstandard names/locations.

Report bugs to <mail@lists.cinelerra-gg.org>.

\end{verbatim}
\endgroup

\section{Thirdparty Parallel Build}
\label{sec:Thirdparty Parallel Build}

The Makefile in the thirdparty build directory employs a set of macros used to create a build rule set of thirdparty library build dependencies.  The standard build sequence of [source, config, build] is used to prepare thirdparty products as static libraries.  Build package dependency can be specified in the Makefile std-build macro call.  These Makefile macro calls define the rules used for each thirdparty build.  The expanded rule definitions may be viewed by using:
\smallskip

\hspace{2em}make -C thirdparty rules
\medskip

Individual package libraries can be rebuilt, via:
\smallskip
\hspace{2em}make -C thirdparty <pkg>-clean;  make -C thirdparty <pkg>
\medskip

The rule targets create the set of thirdparty packages which are built from local source archive copies of thirdparty source code and patches, if needed.  The build rule set of dependencies allows for compiling multiple thirdparty programs simultaneously using maximum computer resources.  This parallel build speeds up the process considerably.  For example, these are full static build timings on the production build machine (full build includes building all thirdparty programs as well as all of Cinelerra):
\medskip

\hspace{2em}
\begin{tabular}{@{}rcr}
        1 cpu & = & 61 mins\\
        12 cpus & = & 7.5 mins\\
        24 cpus & = & 2 mins\\
\end{tabular}

\section{Find Lock Problems with Booby Trap}
\label{sec:Find Lock Problems with Booby Trap}

A Booby Trap is used in CinGG for setting a trap to catch lock problems that might have been missed. \ It will trap boobies only if compile by adding ``-{}-with-booby'' on the configuration command line. \ \ This is the default if you compile using ./bld.sh from the GIT repository. \ It should not interfere with normal execution.
\medskip

If you have the time and inclination, enable -{}-with-booby and send any trap output that you find. \ Maybe you will catch some boobies and if you do, send a snapshot of any boobies you find.
\medskip

There are 2 potential traps:
\begin{itemize}[nosep]
        \item If you try to unlock a lock when it is not locked
        \item If you execute a drawing operation without holding the window lock
\end{itemize}
\medskip

The trap prints the following in the controlling terminal window:
\medskip

\hspace{2em}BOOBY!hspace{2em}{\textless}backtrace{\textgreater}
\medskip

An example backtrace is below along with a hint below on how to analyze:

\begin{lstlisting}[numbers=none]
/home/cin5/bin/./cin(_Z5boobyv+0x3f) [0x557069fa9b2f] /home/cin5/bin/./cin(_ZN13BC_WindowBase9draw_lineEiiiiP9BC_Pixmap+0x3b)0x557069fb9a9b]
/home/cin5/bin/./cin(\_ZN10BC_ListBox11draw_borderEi+0x73)[0x557069f7dc73]
/home/cin5/bin/./cin(+0x9707fb) [0x557069f7e7fb]
/home/cin5/bin/./cin(\ZN10BC\ListBox16center\selectionEv+0x4e)[0x557069f7f2ae]
/home/cin5/bin/plugins/video/sketcher.plugin(_ZN17SketcherCurveList6updateEi+0x1a0)[0x7f1b8002a4c0]
/home/cin5/bin/plugins/video/sketcher.plugin(_ZN18SketcherCurveColor17handle_done_eventEi+0x76)[0x7f1b8002a5f6]
/home/cin5/bin/./cin(_ZN15BC_DialogThread3runEv+0xd8)[0x557069f6fb78]
/home/cin5/bin/./cin(_ZN6Thread10entrypointEPv+0x45)[0x557069fc5995]
/usr/lib/libpthread.so.0(+0x7a9d) [0x7f1b91b4ea9d]
/usr/lib/libc.so.6(clone+0x43) [0x7f1b90accb23]
\end{lstlisting}

To see which routine is reporting the booby key in:
\smallskip

\hspace{2em}c++filt
\smallskip

And then the 2nd line in the backtrace above:
\smallskip

\hspace{2em}\_ZN13BC\_WindowBase9draw\_lineEiiiiP9BC\_Pixmap
\smallskip

It comes back with the routine as:
\smallskip

\hspace{2em}BC\_WindowBase::draw\_line(int, int, int, int, BC\_Pixmap*)
\medskip

\section{Valgrind Support Level}
\label{sec:Valgrind Support Level}

Valgrind is a memory mis-management detector.  It shows you memory leaks, deallocation errors, mismanaged threads, rogue reads/writes, etc.  Cinelerra-GG memory management is designed to work with Valgrind detection methods.  This assists in developing reliable code.  Use of Valgrind points out problems so that they can be fixed.  For example, when this version of Cinelerra shuts down, it deallocates memory instead of just stopping, thus making memory leak detection possible.
\medskip

The best way to compile and run valgrind is to run the developer static build. This takes 2 steps and you must already have gdb and valgrind installed:
\medskip

\begin{enumerate}[nosep]
        \item The standard static build:\newline
                cd /path/cinelerra-5.1\newline
                make clean\newline
                ./bld.sh
        \item run the incremental rebuild for debug objs\newline
                CFLAGS=-ggdb make -j8 rebuild\_all
\end{enumerate}
\medskip

Now your Cinelerra obj has all of the debug stuff. Next run valgrind as root for the most useful results:
\smallskip

\hspace{2em}cd /path/cinelerra-5.1/cinelerra

\hspace{2em}valgrind -{}-log-file=/tmp/log -{}-leak-check=full -{}-num-callers=32 ./ci
\medskip

This runs Cinelerra under the control of valgrind, and produces a log file in /tmp which will list information about any leaks, usually clearly identifiable. \ Be sure to Quit out of Cinelerra normally instead of Ctrl-C or a SEGV otherwise the program does not have a chance to cleanup and there will be some false alarms. But it runs very slowly, and is basically single threaded, which means that race conditions may be impossible to catch... like one thread deletes memory that another thread is currently using. But overall it is a big help and if you test any new features, please email the log output. \ A lot of effort when writing the code was put into trying to be sure that all of the object constructors have matching destructors so that the leaks can be identified. There are already several libraries that create predictable memory leaks and valgrind does a good job for most of these.
\medskip

It is impossible to test everything with valgrind because some things are just too big and slow for a practical test. \ Occasionally you can find a leak or an illegal memory access. There are several false alarms that are difficult to avoid {\textquotedbl}Conditional jump{\textquotedbl} messages, and {\textquotedbl}unhandled DW\_OP\_{\textquotedbl}, but anything with the word {\textquotedbl}illegal{\textquotedbl} in the message is important. Memory leaks that originate in Cinelerra are good to find and fix, but are usually not deadly.

\section{CFLAGS has -Wall}
\label{sec:CFLAGS has -Wall}
When compiling Cinelerra-GG Infinity a CFLAGS option used is "Wall" where the "W" represents warnings and "all" means all.  This causes the compile to check for simple mistakes that can be detected automatically and issue warnings when the code is questionable.  It can also detect situations where the compiler will generate incorrect code, like type-punned pointer.  By turning on this flag, when new code is vetted for predictable mistakes, the code can be corrected before becoming manifested in the application.

\section{Prof2 -- A Profiler}
\label{sec:Prof2 -- A Profiler}

Frequently there is a problem with a program running slow and you do not know why. \ You need a thumbnail analysis of where the program is spending most of its time without all of the overwhelming details. \ This is when a Profiler comes in handy.
\medskip

There are many different profilers available -- this particular one does not do anything special and is fairly ordinary in that it just characterizes frequency of execution of various regions in the program. \ However, it has some pretty good strengths as listed next.
\medskip
\begin{enumerate}[nosep]
        \item It takes very little or no preconditioning, i.e. setup
        \item The effect it has on the running program is minimal
        \item It runs almost at full speed, which is really nice
        \item It is not particularly thread aware
        \item Reports where it is executing at intervals of 100 times a second
\end{enumerate}
\subsection{Setup}

This profiler works on x86\_64 systems and you must be root to compile and run it. \ Also, you must install your operating system's ``iberty'' -- for example, which would be binutils-devel for Fedora or libiberty-dev for Ubuntu 18.
\medskip

Go to the top level Cinelerra directory.

Key in: \ \ \ \ cd prof2

Key in: \ \ \ \ make clean all install

Later, if you wanttitle to remove this from the system, key in: \ \ \ \ make uninstall
\subsection{How to use}

The program you are profiling should be compiled debuggable with stack frame and symbols enabled.
\medskip

To see help, key in: \ \ prof -h
\smallskip

usage: -h [-o path] [-d] [-e] [-p libpath] [-012] [-u \#] cmd args...

\hspace{2em}
\begin{tabular}{@{}ll}
        -o & profile output pathname, -=stdout, -{}-=stderr\\
        -d & debug otitleutput enabled\\
        -e & child debug output enabled\\
        -p & specify path for libprofile.so\\
        -0 & usr+sys cpu timer intervals (sigprof)\\
        -1 & usr only cpu timer intervals (sigvtalrm)\\
        -2 & real time timer intervals (sigalrm)\\
        -u & profile timer interval in usecs\\
\end{tabular}
\medskip

To execute the profiler, key in: \ \ 
\medskip

\hspace{2em}prof -o /tmp/prof\_list.txt ./cin
\medskip

where /tmp/prof\_list.txt is the output file and in this case ``cin'' is the Cinelerra binary file. \ The pid of this command will be displayed on the startup window. \ This comes in handy in the use case where there is a lot of initial load and possible configuration setup inside of Cinelerra and you want to profile plugins and not necessarily all of the setup steps. \ Then you can use the following command in another window to continue running Cinelerra and obtain the more useful information:
\medskip

\hspace{2em}kill -USR1 pid
\medskip

Running this command refreshes the memory maps used for profiling. \ When you are profiling a plugin, you want to run this AFTER the plugin loads.
\medskip

\subsection{Results}

There are 3 sections in the resulting output file of this stochastic quick analysis.
\medskip

\begin{enumerate}[nosep]
        \item The first section is a histogram of the timer intervals of that sample set. \ Each function occupies a region of addresses. \ One hundred times a second, the profiler samples the program address in the region of execution.
        \item In the second section, there is another histogram of the cumulative frequency of all things in the call stack and this should point out who is the culprit. \ For example, a codec calls a bunch of subroutines, the cost of the subroutines is accumulated to the codec parent caller. \ This makes the actual cpu user much more apparent.
        \item The last section is for the library spaces. \ Each library occupies a region and the profiler adds up the time spent in each of the libraries by frequency.
\end{enumerate}
\smallskip

On the very bottom is a 1 line summary which shows you if there is a bad guy and who it is.
\medskip

\subsection{Sample output}

\medskip

%\begin{lstlisting}[numbers=none] %\textwidth

---- profile start ----\\
1020 ticks 43 modules 81412 syms\\
\begin{tabular}{@{}rrp{\linewidth-6em}}
 0.010s & 0.1\% & Autos::copy(long, long, FileXML*, int, int) /mnt0/build5/cinelerra-5.1/bin/cin\\
 0.010s & 0.1\% & BinFolders::copy\_from(BinFolders*) /mnt0/build5/cinelerra-5.1/bin/cin\\
 0.010s & 0.1\% & cstrdup(char const*)     /mnt0/build5/cinelerra-5.1/bin/cin\\
 0.010s & 0.1\% & XMLBuffer::encode\_data(char*, char const*, int) /mnt0/build5/cinelerra-5.1/bin/cin\\
 0.010s & 0.1\% & XMLBuffer::encoded\_length(char const*, int) /mnt0/build5/cinelerra-5.1/bin/cin\\
 0.010s & 0.1\% & PluginClient::send\_configure\_change() /mnt0/build5/cinelerra-5.1/bin/cin\\
 0.010s & 0.1\% & UndoVersion::scan\_lines(UndoHashTable*, char*, char*) /mnt0/.../cin\\
 0.010s & 0.1\% & UndoStackItem::set\_data(char*) /mnt0/build5/cinelerra-5.1/bin/cin\\
 0.010s & 0.1\% & UndoStack::load(\_IO\_FILE*) /mnt0/build5/cinelerra-5.1/bin/cin\\
 0.010s & 0.1\% & BC\_Bitmap::cur\_bfr()     /mnt0/build5/cinelerra-5.1/bin/cin\\
 0.010s & 0.1\% & YUV::init\_tables(int, int*, int*, int*, int*, int*, int*, int*, int*, int*, int*, int*, int*, int*, int*) /mnt0/build5/cinelerra-5.1/bin/cin\\
\end{tabular}\\
...\\
...\\
---- profile calls ----\\
\begin{tabular}{@{}rrl}
 0.010s & 0.1\% & AutoConf::save\_xml(FileXML*)   1.0 /mnt0/build5/cinelerra-5.1/bin/cin\\
 0.010s & 0.1\% & Automation::copy(long, long, FileXML*, int, int)   1.0 /mnt0/.../cin\\
 0.010s & 0.1\% & AWindow::run()             1.0 /mnt0/build5/cinelerra-5.1/bin/cin\\
 0.010s & 0.1\% & Canvas::stop\_single()      1.0 /mnt0/build5/cinelerra-5.1/bin/cin\\
 0.010s & 0.1\% & ColorPicker::new\_gui()     1.0 /mnt0/build5/cinelerra-5.1/bin/cin\\
 0.010s & 0.1\% & ColorWindow::create\_objects()   1.0 /mnt0/build5/cinelerra-5.1/bin/cin\\
 0.010s & 0.1\% & PaletteWheel::draw(float, float)   1.0 /mnt0/build5/cinelerra-5.1/bin/cin\\
 0.010s & 0.1\% & PaletteHex::update()       1.0 /mnt0/build5/cinelerra-5.1/bin/cin\\
 0.010s & 0.1\% & CWindowGUI::draw\_status(int)   1.0 /mnt0/build5/cinelerra-5.1/bin/cin\\
 0.010s & \textbf{0.1\%} & CWindowCanvas::status\_event()   1.0 /mnt0/build5/cinelerra-5.1/bin/cin\\
\end{tabular}\\
...\\
...\\
\begin{tabular}{@{}rrl}
 0.990s & \textbf{9.7\%} & BC\_Xfer::xfer\_slices(int)   1.0 /mnt0/build5/cinelerra-5.1/bin/cin\\
 1.880s & \textbf{18.4\%} & DirectUnit::process\_package(LoadPackage*)   1.0 /mnt0/build5/cinelerra-5.1/bin/cin\\
 1.880s & \textbf{18.4\%} & DirectUnit::rgba8888()     1.0 /mnt0/build5/cinelerra-5.1/bin/cin\\
 3.910s & \textbf{38.3\%} & \_\_init\_array\_end           1.1 /mnt0/build5/cinelerra-5.1/bin/cin\\
 5.450s & \textbf{53.4\%} & LoadClient::run()          1.0 /mnt0/build5/cinelerra-5.1/bin/cin\\
 7.890s & \textbf{77.4\%} & Thread::entrypoint(void*)   1.0 /mnt0/build5/cinelerra-5.1/bin/cin\\
 7.890s & \textbf{77.4\%} & start\_thread               1.0 /lib64/libpthread-2.28.so\\
\end{tabular}\\
----\\
----\\
\begin{tabular}{@{}rrl}
 0.010s & 0.1\%/  0.0\% & /lib64/libm-2.28.so\\
 0.010s & 0.1\%/  0.0\% & /lib64/libexpat.so.1.6.8\\
 0.020s & 0.2\%/  0.1\% & /lib64/libXext.so.6.4.0\\
 0.020s & 0.2\%/  0.1\% & /lib64/libXft.so.2.3.2\\
 0.020s & 0.2\%/  0.1\% & /lib64/libxcb.so.1.1.0\\
 0.040s & 0.4\%/  0.2\% & /lib64/ld-2.28.so\\
 0.050s & 0.5\%/  0.2\% & /lib64/libpng16.so.16.34.0\\
 0.130s & 1.3\%/  0.6\% & /lib64/libX11.so.6.3.0\\
 0.180s & 1.8\%/  0.8\% & /lib64/libz.so.1.2.11\\
 0.200s & 2.0\%/  0.9\% & /lib64/libfontconfig.so.1.12.0\\
 0.380s & 3.7\%/  1.8\% & /lib64/libpthread-2.28.so\\
 1.660s & 16.3\%/ 7.7\% & /lib64/libc-2.28.so\\
 7.480s & 73.3\%/34.7\% & /mnt0/build5/cinelerra-5.1/bin/cin\\
\end{tabular}\\

\textbf{10.200t 0.001u+0.000s 21.566r  47.3\%}
\\
---- profile end ----
%\end{lstlisting}
\medskip

The summary line above in Bold represents the User time, System time, Real time and the percentage is how much Timer time elapsed over Real time so in this case the measurement covers 47.3\% of time. 
\medskip

So why use a Profiler? \ Because it is the ``ls'' for executable functions!!