README

KernelShark is a front-end reader of tracing data.

The official repository is here:
    https://git.kernel.org/pub/scm/utils/trace-cmd/kernel-shark.git

Third Party Software:
------------------------------------------------------------
KernelShark has the following external dependencies:
  Cmake, Json-C, OpenGL/Glut, Qt6Base, libtraceevent, libtracefs, trace-cmd
  and FreeSans font.

1. In order to install the packages on Ubuntu do the following:
    sudo apt-get install build-essential git cmake libjson-c-dev -y
    sudo apt-get install freeglut3-dev libxmu-dev libxi-dev -y
    sudo apt-get install flex bison -y
    sudo apt-get install fonts-freefont-ttf -y
    sudo apt-get install qt6-base-dev qt6-scxml-dev -y
    sudo apt-get install libtraceevent-dev libtracefs-dev libtracecmd-dev trace-cmd -y

1.1 If you want to be able to generate Doxygen documentation:
    sudo apt-get install graphviz doxygen-gui -y


2. In order to install the packages on Fedora, as root do the following:
    sudo dnf install gcc gcc-c++ git cmake json-c-devel -y
    sudo dnf install freeglut-devel redhat-rpm-config -y
    sudo dnf install flex bison -y
    sudo dnf install gnu-free-sans-fonts -y
    sudo dnf install qt6-qtbase-devel qt6-qtscxml-devel -y
    sudo dnf install libtraceevent-devel libtracefs-devel libtracecmd-devel trace-cmd -y

2.1 If you want to be able to generate Doxygen documentation:
    sudo dnf install graphviz doxygen -y

Building:
------------------------------------------------------------
1. Building and install KernelShark GUI:

    cd kernel-shark/build
    cmake ../
    make
    sudo ./install_gui.sh

1.1 In order to create a Doxygen documentation add -D_DOXYGEN_DOC=1
as a CMake Command-Line option (see the example below).

1.2 KernelShark has multiple build types. By default, the build type is
RelWithDebInfo, which will build a release candidate with debug information.
To change the type, pass in the option CMAKE_BUILD_TYPE=<type> (see the
example below).

    cmake -DCMAKE_BUILD_TYPE=Debug           - for "-g" option
    cmake -DCMAKE_BUILD_TYPE=Release         - for "-O3" option
    cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo  - for "-g -O2" option (default)
    cmake -DCMAKE_BUILD_TYPE=MinSizeRel      - for "-Os" option

1.3 In addition to the standard CMake build types (Debug, Release,
RelWithDebInfo, MinSizeRel) KernelShark supports a "Package" build type.
By default this build type adds the "-O3" compiler flag. Package maintainers
can chose their own compiler flags by providing the corresponding
CMAKE_XXXX_FLAGS_PACKAGE Command-Line options (see the example below).

-- Note that when built as a "Package" the RPATH-s of the executables are
set directly to _INSTALL_PREFIX/lib/kernelshark/

1.4 After building the code "kernel-shark/lib" will contain all libraries
and "kernel-shark/bin" will contain all executables.

1.5 Use the script "cmake_clean.sh" if you want to delete all already
compiled objects and all files generated by CMake.

    cd kernel-shark/build
    ./cmake_clean.sh

1.6 By default, installation prefix is "/usr/local". It can be changed using
-D_INSTALL_PREFIX= as a CMake Command-Line option (see the example below).

2. To install libkshark-devel do:
    sudo ./install_libkshark-devel.sh

    This will install all components needed in order to use "libkshark".
    Note that if you just use:

    sudo make install

    this will install both the GUI and libkshark-devel.

3.  In order to uninstall KernelShark (no matter what has been installed) do:
    cd kernel-shark/build
    ./cmake_uninstall.sh


CMake examples:

    cmake -D_DOXYGEN_DOC=1 -D_INSTALL_PREFIX=/usr ../

    cmake -DCMAKE_BUILD_TYPE=Package -DCMAKE_C_FLAGS_PACKAGE="-O3 -pedantic"  ../

External plugins:
------------------------------------------------------------
    KernelShark also supports stand-alone plugin except for build-in. There is
    a real example under https://source.denx.de/Xenomai/xenomai/-/tree/next/tracing/kernelshark/,
    which is to visualize out-of-band state of realtime task with hollow cobalt
    blue box mainly when there is cobalt context switches in Xenomai. As its
    implemention mainly refers to build-in plugin-sched_events, it shares common
    plugin features such as clickable shapes.

Contributions:
------------------------------------------------------------
3. For questions about the use of the library, please send email to:
   linux-trace-users@vger.kernel.org

   Subscribe: http://vger.kernel.org/vger-lists.html#linux-trace-users
   Archives: https://lore.kernel.org/linux-trace-users/

3.1 For contributions to development, please send patches to:
    linux-trace-devel@vger.kernel.org

   Subscribe: http://vger.kernel.org/vger-lists.html#linux-trace-devel
   Archives: https://lore.kernel.org/linux-trace-devel/

3.2 Note, this project follows the style of submitting patches as described
by the Linux kernel.

    https://www.kernel.org/doc/html/v5.4/process/submitting-patches.html