Difference between revisions of "GstShark - Getting Started"

From RidgeRun Developer Connection
Jump to: navigation, search
m
(→‎Meson)
 
(20 intermediate revisions by 7 users not shown)
Line 1: Line 1:
−
{{GstShark/Head |previous=|next=Generating trace files|keywords=|content=This page will describe how to get and setup Ridgerun's GstShark suite of tools for profiling and benchmarking GStreamer pipelines.}}
+
{{GstShark/Head |previous=|next=Install Eclipse plugin|metakeywords=|metadescription=This page will describe how to get and setup Ridgerun's GstShark suite of tools for profiling and benchmarking GStreamer pipelines.}}
  
−
= Getting the code =
+
== Getting the code ==
  
 
GstShark is an open-source source project by Ridgerun Engineering. It is publicly available here[https://github.com/RidgeRun/gst-shark].
 
GstShark is an open-source source project by Ridgerun Engineering. It is publicly available here[https://github.com/RidgeRun/gst-shark].
Line 16: Line 16:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
= Dependencies =
+
== Dependencies ==
  
−
== GStreamer 1.7.1+ ==
+
=== GStreamer 1.7.1+ ===
  
 
GstShark leverages GStreamer's tracing subsystem, which was added in GStreamer 1.7.1.
 
GstShark leverages GStreamer's tracing subsystem, which was added in GStreamer 1.7.1.
Line 49: Line 49:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
== Graphviz ==
+
=== Graphviz ===
  
−
Graphviz is used to display the pipeline diagrams as obtained by the [[GstShark - Graphic tracer| graphic tracer]]. According to your distribution and version of your distribution, the Graphviz library might be called graphviz-dev or libgraphviz-dev. To read the graphics resulting from the tracer later, the package graphviz is required. Check your distribution's package lists for a suitable packages. For recent Ubuntu versions:
+
Graphviz is used to display the pipeline diagrams as obtained by the [[GstShark - Graphic tracer| graphic tracer]]. According to your distribution and version of your distribution, the Graphviz library might be called graphviz-dev or libgraphviz-dev. To read the graphics resulting from the tracer later, the package graphviz is required. Check your distribution's package lists for a suitable package. For recent Ubuntu versions:
  
 
<syntaxhighlight lang=bash>
 
<syntaxhighlight lang=bash>
Line 57: Line 57:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
== octave, epstool and babeltrace ==
+
=== octave, epstool and babeltrace ===
  
−
Octave scripts are provided to generate charts of the traces. Octave scripts use babeltrace to parse the trace files to be used by Octave and epstool to generate the PDF outputs. Octave, epstool and babeltrace are not required for compiling GstShark, but are required to run the scripts. To install octave, epstool and babeltrace on Ubuntu:
+
Octave scripts are provided to generate charts of the traces. Octave scripts use babeltrace to parse the trace files to be used by Octave and epstool to generate the PDF outputs. Octave, epstool and babeltrace are not required for compiling GstShark but are required to run the scripts. To install octave, epstool and babeltrace on Ubuntu:
  
 
<syntaxhighlight lang=bash>
 
<syntaxhighlight lang=bash>
−
$ sudo apt install octave epstool babeltrace
+
$ sudo apt install octave epstool babeltrace gtk-doc-tools
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
== Eclipse Mars.2 ==
+
=== Eclipse Mars.2 ===
  
 
GstShark includes optional experimental support to generate charts using Eclipse. Currently, only Eclipse Mars.2 (4.5.2) is supported. Eclipse Mars.2 can be downloaded from: https://www.eclipse.org/downloads/packages/release/Mars/2
 
GstShark includes optional experimental support to generate charts using Eclipse. Currently, only Eclipse Mars.2 (4.5.2) is supported. Eclipse Mars.2 can be downloaded from: https://www.eclipse.org/downloads/packages/release/Mars/2
  
−
= Building GstShark Tracers =
+
== Building and Installing GstShark Tracers ==
  
−
The GstShark project comes packed as a typical GNU open source project. Use autogen/make to build the project:
+
GstShark project supports both meson and autotools build systems
 +
 
 +
=== Meson===
 +
'''NOTE''': If you are on RedHat8/CentOS8 use <code>ninja-build</code> instead of <code>ninja</code>
 +
 
 +
Install meson to at least v0.58:
 +
 
 +
<syntaxhighlight lang=bash>
 +
sudo apt install python3 python3-pip ninja-build
 +
pip3 install --user meson
 +
sudo cp ~/.local/bin/meson /usr/bin/meson
 +
</syntaxhighlight>
 +
 
 +
Configure and build:
 +
 
 +
<syntaxhighlight lang=bash>
 +
meson builddir --prefix /usr/
 +
ninja -C builddir
 +
</syntaxhighlight>
 +
 
 +
To install:
 +
 
 +
<syntaxhighlight lang=bash>
 +
ninja install -C builddir
 +
</syntaxhighlight>
 +
 
 +
To run tests:
 +
<syntaxhighlight lang=bash>
 +
ninja test -C builddir
 +
</syntaxhighlight>
 +
 
 +
The following configurations are available beside the normal meson ones:
 +
 
 +
{| class="wikitable"
 +
|- style="font-weight:bold;"
 +
! Option
 +
! Description
 +
! Default
 +
|-
 +
| enable-tests
 +
| Enable building and running the unit tests
 +
| true
 +
|-
 +
| enable-check
 +
| Enable building and running unit tests using gst-check (requires enable-tests)
 +
| true
 +
|-
 +
| enable-plotting
 +
| Enable pipeline plotting capabilities
 +
| enabled
 +
|-
 +
| enable-docs
 +
| Enable generation of documentation
 +
| true
 +
|}
 +
 
 +
=== Autotools ===
  
 
<syntaxhighlight lang=bash>
 
<syntaxhighlight lang=bash>
Line 94: Line 150:
 
       <td>RidgeRun's Embedded FS</td>
 
       <td>RidgeRun's Embedded FS</td>
 
       <td>--prefix /usr/</td>
 
       <td>--prefix /usr/</td>
−
    </tr>
 
−
    <tr>
 
−
      <td>MacOSX</td>
 
−
      <td>--prefix /opt/local/</td>
 
 
     </tr>
 
     </tr>
 
     <tr>
 
     <tr>
Line 104: Line 156:
 
     </tr>
 
     </tr>
 
     <tr>
 
     <tr>
−
       <td>Tegra X1/X2</td>
+
       <td>NVIDIA Jetson SoCs<br>TX1 TX2 Nano Xavier NX</td>
 
       <td>--prefix /usr/ --libdir /usr/lib/aarch64-linux-gnu/</td>
 
       <td>--prefix /usr/ --libdir /usr/lib/aarch64-linux-gnu/</td>
 
     </tr>
 
     </tr>
Line 113: Line 165:
  
 
For other distributions and platforms, the commands may need to be adjusted. Please [[GstShark - Contact Us|contact us]] for details on how to compile for your platform.
 
For other distributions and platforms, the commands may need to be adjusted. Please [[GstShark - Contact Us|contact us]] for details on how to compile for your platform.
−
 
−
= Installing GstShark Tracers =
 
  
 
To install the tracers, use the install rules of the Makefile.  
 
To install the tracers, use the install rules of the Makefile.  
Line 122: Line 172:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
For other distributions and platforms, the command may need to be adjusted. Please [[GstShark - Contact Us|contact us]] for details on how to install for your platform.
+
= Installing GstShark on macOS using homebrew =
 +
 
 +
[https://brew.sh Homebrew] supports the packages used by GstShark to create the plot files.  Install Homebrew if you feel comfortable installing software outside of the Apple Store.
 +
 
 +
== Update installed packages ==
 +
 
 +
If you have homebrew installed, consider updating homebrew and upgrading your packages.
 +
 
 +
<pre>
 +
brew update
 +
brew upgrade
 +
</pre>
 +
 
 +
== Install GStreamer ==
 +
 
 +
GstShark leverages GStreamer's tracing subsystem, which was added in GStreamer 1.7.1.  To check your current GStreamer version run the following command:
 +
<pre>
 +
$ gst-launch-1.0 --version
 +
gst-launch-1.0 version 1.7.1
 +
GStreamer 1.7.1
 +
Unknown package origin
 +
</pre>
 +
 
 +
If you do not have GStreamer installed at all, run the following commands:
 +
<pre>
 +
brew install gstreamer
 +
brew link gstreamer
 +
</pre>
 +
 
 +
== Install graphing tools ==
 +
 
 +
A set of graphing packages are used to GstShark.
 +
 
 +
<pre>
 +
brew install octave graphviz octave epstool
 +
</pre>
 +
 
 +
== Build and install babeltrace ==
 +
 
 +
Babeltrace isn't available as part of homebrew at the time of this writing.
 +
 
 +
<pre>
 +
brew install autoconf automake bison
 +
 
 +
mkdir -p ~/projects
 +
cd ~/projects
 +
git clone https://github.com/efficios/babeltrace.git -b v1.5.8
 +
cd babeltrace
 +
./bootstrap
 +
PATH="/usr/local/opt/bison/bin:$PATH" ./configure
 +
PATH="/usr/local/opt/bison/bin:$PATH" make
 +
sudo make install
 +
</pre>
 +
 
 +
== Build and install GstShark tracers ==
 +
 
 +
With all the dependencies in place, you can now build GstShark.
 +
 
 +
<pre>
 +
brew install gtk-doc
 +
 
 +
mkdir -p ~/projects
 +
cd ~/projects
 +
git clone https://github.com/RidgeRun/gst-shark
 +
cd gst-shark
 +
./autogen.sh
 +
make
 +
</pre>
 +
 
 +
= Installing GstShark on Yocto =
 +
 
 +
== Meta-RidgeRun ==
 +
 
 +
In order to use gst-shark easily, we recommend using the meta-ridgerun layer (https://github.com/RidgeRun/meta-ridgerun)
 +
 
 +
This already has the gst-shark recipe integrated.
 +
 
 +
The meta-ridgerun layer has to be added to the bblayers.conf. A full example is shown (note the last line):
 +
 
 +
<pre>
 +
LCONF_VERSION = "7"
 +
 
 +
BBPATH = "${TOPDIR}"
 +
BSPDIR := "${@os.path.abspath(os.path.dirname(d.getVar('FILE', True)) + '/../..')}"
 +
 
 +
BBFILES ?= ""
 +
BBLAYERS = " \
 +
  ${BSPDIR}/sources/poky/meta \
 +
  ${BSPDIR}/sources/poky/meta-poky \
 +
  \
 +
  ${BSPDIR}/sources/meta-openembedded/meta-oe \
 +
  ${BSPDIR}/sources/meta-openembedded/meta-multimedia \
 +
  \
 +
  ${BSPDIR}/sources/meta-freescale \
 +
  ${BSPDIR}/sources/meta-freescale-3rdparty \
 +
  ${BSPDIR}/sources/meta-freescale-distro \
 +
"
 +
 
 +
# i.MX Yocto Project Release layers
 +
BBLAYERS += " ${BSPDIR}/sources/meta-fsl-bsp-release/imx/meta-bsp "
 +
BBLAYERS += " ${BSPDIR}/sources/meta-fsl-bsp-release/imx/meta-sdk "
 +
BBLAYERS += " ${BSPDIR}/sources/meta-browser "
 +
BBLAYERS += " ${BSPDIR}/sources/meta-openembedded/meta-gnome "
 +
BBLAYERS += " ${BSPDIR}/sources/meta-openembedded/meta-networking "
 +
BBLAYERS += " ${BSPDIR}/sources/meta-openembedded/meta-python "
 +
BBLAYERS += " ${BSPDIR}/sources/meta-openembedded/meta-filesystems "
 +
BBLAYERS += " ${BSPDIR}/sources/meta-qt5 "
 +
 
 +
BBLAYERS += " ${BSPDIR}/sources/meta-ridgerun "
 +
</pre>
 +
 
 +
== local.conf configuration ==
 +
 
 +
Once the meta-ridgerun is added, then the local.conf must be modified to include gst-shark as follows:
 +
 
 +
IMAGE_INSTALL_append = " gst-shark "
 +
 
 +
Gst-Shark uses gst-tracers in order to retrieve information and provide it to the user. By default, GStreamer doesn't have some hooks enabled in Yocto builds, so it is required to enable them. This is accomplished by adding on the local.conf of the project, the next line:
 +
 
 +
PACKAGECONFIG_append_pn-gstreamer1.0 = "gst-tracer-hooks"
 +
 
 +
For Yocto Dunfell and newer the required configuration changed:
 +
 
 +
PACKAGECONFIG_append_pn-gstreamer1.0 = " tracer-hooks"
 +
 
 +
An example of local.conf would be:
 +
 
 +
<pre>
 +
MACHINE ??= 'imx8mmevk'
 +
DISTRO ?= 'fsl-imx-wayland'
 +
PACKAGE_CLASSES ?= "package_rpm"
 +
EXTRA_IMAGE_FEATURES ?= "tools-debug debug-tweaks"
 +
 
 +
INHIBIT_PACKAGE_STRIP = "1"
 +
 
 +
USER_CLASSES ?= "buildstats image-mklibs image-prelink"
 +
PATCHRESOLVE = "noop"
 +
BB_DISKMON_DIRS ??= "\
 +
    STOPTASKS,${TMPDIR},1G,100K \
 +
    STOPTASKS,${DL_DIR},1G,100K \
 +
    STOPTASKS,${SSTATE_DIR},1G,100K \
 +
    STOPTASKS,/tmp,100M,100K \
 +
    ABORT,${TMPDIR},100M,1K \
 +
    ABORT,${DL_DIR},100M,1K \
 +
    ABORT,${SSTATE_DIR},100M,1K \
 +
    ABORT,/tmp,10M,1K"
 +
PACKAGECONFIG_append_pn-qemu-native = " sdl"
 +
PACKAGECONFIG_append_pn-nativesdk-qemu = " sdl"
 +
CONF_VERSION = "1"
  
−
= Installing GstShark Eclipse Plugins =
+
IMAGE_INSTALL_append = " gst-shark "
  
−
The Eclipse plugin is included in the repository, but it is also available from a Ridgerun repository. For details on how to install the Eclipse plugin, visit the [[GstShark - Install Eclipse plugin|Install Eclipse plugin]] page.
+
PACKAGECONFIG_append_pn-gstreamer1.0 = "gst-tracer-hooks"
 +
</pre>
  
−
{{GstShark/Foot |previous=|next=Generating trace files}}
+
{{GstShark/Foot |previous=|next=Install Eclipse plugin}}

Latest revision as of 12:24, 13 July 2023




  Index Next: Install Eclipse plugin


GstShark
GstShark
Getting Started
Generating trace files
Tracer Parameters
Available Tracers
Results
Visualization Tools
Examples
Contact Us



Getting the code

GstShark is an open-source source project by Ridgerun Engineering. It is publicly available here[1].

You can download the source using git: 

$ git clone git@github.com:RidgeRun/gst-shark.git

OR 

$ git clone https://github.com/RidgeRun/gst-shark/

Dependencies

GStreamer 1.7.1+

GstShark leverages GStreamer's tracing subsystem, which was added in GStreamer 1.7.1.

Most modern Linux distributions include GStreamer 1.7.1 (or newer) in their official package repositories. If this is not your case, refer to the this guide to manually install the latest GStreamer version alongside the one installed by your system.

To check your current GStreamer version run the following command: 

$ gst-launch-1.0 --version
gst-launch-1.0 version 1.7.1
GStreamer 1.7.1
Unknown package origin

If you do not have GStreamer installed at all, check the version available using the regular package tools for your distribution. For example, in Ubuntu run the following commands: 

$ apt-cache showpkg libgstreamer1.0-0
Package: libgstreamer1.0-0
Versions:
1.6.3-1ubuntu1 (/var/lib/apt/lists/cr.archive.ubuntu.com_ubuntu_dists_wily-proposed_main_binary-amd64_Packages) 
 ...

And, if the version is above 1.7.1, install it with your distribution's tools. For example, in Ubuntu use: 

$ sudo apt install libgstreamer1.0-dev

Graphviz

Graphviz is used to display the pipeline diagrams as obtained by the graphic tracer. According to your distribution and version of your distribution, the Graphviz library might be called graphviz-dev or libgraphviz-dev. To read the graphics resulting from the tracer later, the package graphviz is required. Check your distribution's package lists for a suitable package. For recent Ubuntu versions: 

$ sudo apt install graphviz libgraphviz-dev

octave, epstool and babeltrace

Octave scripts are provided to generate charts of the traces. Octave scripts use babeltrace to parse the trace files to be used by Octave and epstool to generate the PDF outputs. Octave, epstool and babeltrace are not required for compiling GstShark but are required to run the scripts. To install octave, epstool and babeltrace on Ubuntu: 

$ sudo apt install octave epstool babeltrace gtk-doc-tools

Eclipse Mars.2

GstShark includes optional experimental support to generate charts using Eclipse. Currently, only Eclipse Mars.2 (4.5.2) is supported. Eclipse Mars.2 can be downloaded from: https://www.eclipse.org/downloads/packages/release/Mars/2

Building and Installing GstShark Tracers

GstShark project supports both meson and autotools build systems

Meson

NOTE: If you are on RedHat8/CentOS8 use ninja-build instead of ninja

Install meson to at least v0.58: 

sudo apt install python3 python3-pip ninja-build
pip3 install --user meson
sudo cp ~/.local/bin/meson /usr/bin/meson

Configure and build: 

meson builddir --prefix /usr/
ninja -C builddir

To install: 

ninja install -C builddir

To run tests: 

ninja test -C builddir

The following configurations are available beside the normal meson ones:

Option Description Default
enable-tests Enable building and running the unit tests true
enable-check Enable building and running unit tests using gst-check (requires enable-tests) true
enable-plotting Enable pipeline plotting capabilities enabled
enable-docs Enable generation of documentation true

Autotools

$ ./autogen.sh $OPTIONS # CHOOSE THE APPROPRIATE CONFIGURATION FROM THE TABLE BELOW
$ make

For the most common build targets, the recommended options are listed below.

System Configure Option
Ubuntu 64 bits --prefix /usr/ --libdir /usr/lib/x86_64-linux-gnu/
RidgeRun's Embedded FS --prefix /usr/
Raspbian/Raspberry Pi --prefix /usr/lib/ --libdir /usr/lib/arm-linux-gnueabihf/
NVIDIA Jetson SoCs
TX1 TX2 Nano Xavier NX		 --prefix /usr/ --libdir /usr/lib/aarch64-linux-gnu/
Table 1. Platform configuration options

For other distributions and platforms, the commands may need to be adjusted. Please contact us for details on how to compile for your platform.

To install the tracers, use the install rules of the Makefile. 

$ sudo make install

Installing GstShark on macOS using homebrew

Homebrew supports the packages used by GstShark to create the plot files. Install Homebrew if you feel comfortable installing software outside of the Apple Store.

Update installed packages

If you have homebrew installed, consider updating homebrew and upgrading your packages. 

brew update
brew upgrade

Install GStreamer

GstShark leverages GStreamer's tracing subsystem, which was added in GStreamer 1.7.1. To check your current GStreamer version run the following command: 

$ gst-launch-1.0 --version
gst-launch-1.0 version 1.7.1
GStreamer 1.7.1
Unknown package origin

If you do not have GStreamer installed at all, run the following commands: 

brew install gstreamer
brew link gstreamer

Install graphing tools

A set of graphing packages are used to GstShark. 

brew install octave graphviz octave epstool

Build and install babeltrace

Babeltrace isn't available as part of homebrew at the time of this writing. 

brew install autoconf automake bison 

mkdir -p ~/projects
cd ~/projects
git clone https://github.com/efficios/babeltrace.git -b v1.5.8
cd babeltrace
./bootstrap
PATH="/usr/local/opt/bison/bin:$PATH" ./configure
PATH="/usr/local/opt/bison/bin:$PATH" make
sudo make install

Build and install GstShark tracers

With all the dependencies in place, you can now build GstShark. 

brew install gtk-doc

mkdir -p ~/projects
cd ~/projects
git clone https://github.com/RidgeRun/gst-shark
cd gst-shark
./autogen.sh
make

Installing GstShark on Yocto

Meta-RidgeRun

In order to use gst-shark easily, we recommend using the meta-ridgerun layer (https://github.com/RidgeRun/meta-ridgerun)

This already has the gst-shark recipe integrated.

The meta-ridgerun layer has to be added to the bblayers.conf. A full example is shown (note the last line): 

LCONF_VERSION = "7"

BBPATH = "${TOPDIR}"
BSPDIR := "${@os.path.abspath(os.path.dirname(d.getVar('FILE', True)) + '/../..')}"

BBFILES ?= ""
BBLAYERS = " \
  ${BSPDIR}/sources/poky/meta \
  ${BSPDIR}/sources/poky/meta-poky \
  \
  ${BSPDIR}/sources/meta-openembedded/meta-oe \
  ${BSPDIR}/sources/meta-openembedded/meta-multimedia \
  \
  ${BSPDIR}/sources/meta-freescale \
  ${BSPDIR}/sources/meta-freescale-3rdparty \
  ${BSPDIR}/sources/meta-freescale-distro \
"

# i.MX Yocto Project Release layers
BBLAYERS += " ${BSPDIR}/sources/meta-fsl-bsp-release/imx/meta-bsp "
BBLAYERS += " ${BSPDIR}/sources/meta-fsl-bsp-release/imx/meta-sdk "
BBLAYERS += " ${BSPDIR}/sources/meta-browser "
BBLAYERS += " ${BSPDIR}/sources/meta-openembedded/meta-gnome "
BBLAYERS += " ${BSPDIR}/sources/meta-openembedded/meta-networking "
BBLAYERS += " ${BSPDIR}/sources/meta-openembedded/meta-python "
BBLAYERS += " ${BSPDIR}/sources/meta-openembedded/meta-filesystems "
BBLAYERS += " ${BSPDIR}/sources/meta-qt5 "

BBLAYERS += " ${BSPDIR}/sources/meta-ridgerun "

local.conf configuration

Once the meta-ridgerun is added, then the local.conf must be modified to include gst-shark as follows: 

IMAGE_INSTALL_append = " gst-shark "

Gst-Shark uses gst-tracers in order to retrieve information and provide it to the user. By default, GStreamer doesn't have some hooks enabled in Yocto builds, so it is required to enable them. This is accomplished by adding on the local.conf of the project, the next line: 

PACKAGECONFIG_append_pn-gstreamer1.0 = "gst-tracer-hooks"

For Yocto Dunfell and newer the required configuration changed: 

PACKAGECONFIG_append_pn-gstreamer1.0 = " tracer-hooks"

An example of local.conf would be: 

MACHINE ??= 'imx8mmevk'
DISTRO ?= 'fsl-imx-wayland'
PACKAGE_CLASSES ?= "package_rpm"
EXTRA_IMAGE_FEATURES ?= "tools-debug debug-tweaks"

INHIBIT_PACKAGE_STRIP = "1"

USER_CLASSES ?= "buildstats image-mklibs image-prelink"
PATCHRESOLVE = "noop"
BB_DISKMON_DIRS ??= "\
    STOPTASKS,${TMPDIR},1G,100K \
    STOPTASKS,${DL_DIR},1G,100K \
    STOPTASKS,${SSTATE_DIR},1G,100K \
    STOPTASKS,/tmp,100M,100K \
    ABORT,${TMPDIR},100M,1K \
    ABORT,${DL_DIR},100M,1K \
    ABORT,${SSTATE_DIR},100M,1K \
    ABORT,/tmp,10M,1K"
PACKAGECONFIG_append_pn-qemu-native = " sdl"
PACKAGECONFIG_append_pn-nativesdk-qemu = " sdl"
CONF_VERSION = "1"

IMAGE_INSTALL_append = " gst-shark "

PACKAGECONFIG_append_pn-gstreamer1.0 = "gst-tracer-hooks"


  Index Next: Install Eclipse plugin


Retrieved from "http://developer.ridgerun.com/wiki/index.php?title=GstShark_-_Getting_Started&oldid=49805"