Difference between revisions of "Developers"

From sigrok
Jump to navigation Jump to search
m (Added "PV with clang" hint)
(20 intermediate revisions by 5 users not shown)
Line 8: Line 8:


* [http://sigrok.org/api/libsigrok/unstable/index.html libsigrok API]
* [http://sigrok.org/api/libsigrok/unstable/index.html libsigrok API]
* [http://sigrok.org/api/libsigrokdecode/unstable/index.html libsigrokdecode API]
* [[Protocol decoder HOWTO]]
* [[Protocol decoder HOWTO]]
* [[Protocol decoder API]]
* [[Protocol decoder API]]
* [[Formats and structures]]
* [[Formats and structures]]
* [[Hardware driver API]]
* [[Hardware driver API]]
* [[Input API]]
* [[Portability]]
* [[Output API]]
* [[IO API]] (outdated)


== Development guidelines ==
== Development guidelines ==
Line 23: Line 22:
* [http://sigrok.org/gitweb/?p=libsigrokdecode.git;a=blob;f=HACKING;hb=HEAD libsigrokdecode]
* [http://sigrok.org/gitweb/?p=libsigrokdecode.git;a=blob;f=HACKING;hb=HEAD libsigrokdecode]
* [http://sigrok.org/gitweb/?p=sigrok-cli.git;a=blob;f=HACKING;hb=HEAD sigrok-cli]
* [http://sigrok.org/gitweb/?p=sigrok-cli.git;a=blob;f=HACKING;hb=HEAD sigrok-cli]
* [http://sigrok.org/gitweb/?p=sigrok-qt.git;a=blob;f=HACKING;hb=HEAD sigrok-qt]
<!-- * [http://sigrok.org/gitweb/?p=sigrok-qt.git;a=blob;f=HACKING;hb=HEAD sigrok-qt]
* [http://sigrok.org/gitweb/?p=sigrok-gtk.git;a=blob;f=HACKING;hb=HEAD sigrok-gtk]
* [http://sigrok.org/gitweb/?p=sigrok-gtk.git;a=blob;f=HACKING;hb=HEAD sigrok-gtk] -->
* [http://sigrok.org/gitweb/?p=pulseview.git;a=blob;f=HACKING;hb=HEAD PulseView]
* [http://sigrok.org/gitweb/?p=pulseview.git;a=blob;f=HACKING;hb=HEAD PulseView]
* [http://sigrok.org/gitweb/?p=sigrok-firmware-fx2lafw.git;a=blob;f=HACKING;hb=HEAD sigrok-firmware-fx2lafw]
* [http://sigrok.org/gitweb/?p=sigrok-firmware-fx2lafw.git;a=blob;f=HACKING;hb=HEAD sigrok-firmware-fx2lafw]
Line 32: Line 31:
This is a list of pages we use while working through new features or designs. They are working documents, not official API or feature documentation.
This is a list of pages we use while working through new features or designs. They are working documents, not official API or feature documentation.


* [[New trigger specification]]
* <s>[[New trigger specification]]</s>
* [[GUI design]]
* <s>[[High precision analog]]</s>
* [[High precision analog]]
* <s>[[Probe Groups‎]]</s>
* [[Improved Configuration Enumeration]]
* <s>[[Input/output API revamp]]</s>
* [[File format:sigrok/v3]]
* [[Domain-specific measurements and analysis]]
* [[Feeding hardware-decoded packets into libsigrok]]
* [[Sending data sequences to devices]]


== Debugging ==
== Debugging ==
Line 40: Line 45:
If you would like to see the output of the sr_dbg() or sr_err() functions you can use one of the following [[sigrok-cli]] options:
If you would like to see the output of the sr_dbg() or sr_err() functions you can use one of the following [[sigrok-cli]] options:


<small>
  $ '''export SIGROK_DEBUG=1'''
  $ '''export SIGROK_DEBUG=1'''
or
  $ '''sigrok-cli -l 5 ''<options>'' '''
  $ '''sigrok-cli -l 5 ''<options>'' '''
</small>
The '''5''' above is the log level. The following levels are available:
* 0: no output at all
* 1: error messages
* 2: warnings (the default)
* 3: informational messages
* 4: debug
* 5: spew
== Temporarily build PulseView with clang ==
$ '''cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ .'''
== PulseView and GDB ==
[[PulseView]] can be a bit tricky to debug as running it in GDB can stall the entire X11 session when PulseView crashes. This can be worked around, however. One approach is running GDB with a script that automatically creates a backtrace and terminates GDB (and thus, PulseView):
<small>
$ '''gdb --command=auto_bt.gdb build/bin/pulseview'''
</small>
with auto_bt.gdb containing lines as these:
<small>
run -l 5
thread apply all bt
quit
</small>
Another approach is to run gdb in tmux. When X11 freezes you can switch to a different virtual console, reattach to tmux, and continue the debugging process from there. This approach also makes it easier to use breakpoints.


== Valgrind ==
== Valgrind ==
Line 47: Line 86:
The following instructions outline how you can use [http://valgrind.org/ valgrind] to help find memory-related bugs in the sigrok libraries and frontends.
The following instructions outline how you can use [http://valgrind.org/ valgrind] to help find memory-related bugs in the sigrok libraries and frontends.


'''Setup:'''
'''Debug packages setup (optional):'''


In order to get more useful output from valgrind you can (optionally) install various '''-dbg''' packages (if your distro provides them).
In order to get more useful output from valgrind you can (optionally) install various '''-dbg''' packages (if your distro provides them).
Line 56: Line 95:
  $ '''apt-get install libgcc1-dbg libpcre3-dbg libglib2.0-0-dbg libftdi1-dbg zlib1g-dbg libasound2-dbg python3-dbg valgrind-dbg'''
  $ '''apt-get install libgcc1-dbg libpcre3-dbg libglib2.0-0-dbg libftdi1-dbg zlib1g-dbg libasound2-dbg python3-dbg valgrind-dbg'''
</small>
</small>
 
<!--
For GTK+ based frontends (e.g. [[sigrok-gtk]]) additional packages might be helpful in some cases:
For GTK+ based frontends (e.g. [[sigrok-gtk]]) additional packages might be helpful in some cases:


Line 66: Line 105:
   '''libxrender1-dbg libxext6-db libxrandr2-dbg'''
   '''libxrender1-dbg libxext6-db libxrandr2-dbg'''
</small>
</small>
-->


For Qt based frontends (e.g. [[sigrok-qt]] or [[PulseView]]) additional packages might be helpful in some cases:
For Qt and/or Boost based frontends (e.g. [[PulseView]]) additional packages might be helpful in some cases:


<small>
<small>
Line 82: Line 122:
  $ '''cd libsigrokdecode; CFLAGS="-g -O0" ./configure --prefix=$HOME/sr && make install'''
  $ '''cd libsigrokdecode; CFLAGS="-g -O0" ./configure --prefix=$HOME/sr && make install'''
  $ '''cd sigrok-cli; CFLAGS="-g -O0" PKG_CONFIG_PATH=$HOME/sr/lib/pkgconfig ./configure --prefix=$HOME/sr && make install'''
  $ '''cd sigrok-cli; CFLAGS="-g -O0" PKG_CONFIG_PATH=$HOME/sr/lib/pkgconfig ./configure --prefix=$HOME/sr && make install'''
$ '''cd sigrok-gtk; CFLAGS="-g -O0" PKG_CONFIG_PATH=$HOME/sr/lib/pkgconfig ./configure --prefix=$HOME/sr && make install'''
<!-- $ '''cd sigrok-gtk; CFLAGS="-g -O0" PKG_CONFIG_PATH=$HOME/sr/lib/pkgconfig ./configure --prefix=$HOME/sr && make install'''
  $ '''cd sigrok-qt; CFLAGS="-g -O0" PKG_CONFIG_PATH=$HOME/sr/lib/pkgconfig qmake && make && cp sigrok-qt $HOME/sr/bin'''
  $ '''cd sigrok-qt; CFLAGS="-g -O0" PKG_CONFIG_PATH=$HOME/sr/lib/pkgconfig qmake && make && cp sigrok-qt $HOME/sr/bin''' -->
  $ '''cd pulseview; CXXFLAGS="-g -O0" PKG_CONFIG_PATH=$HOME/sr/lib/pkgconfig cmake . && make && cp pulseview $HOME/sr/bin'''
  $ '''cd pulseview; CXXFLAGS="-g -O0" PKG_CONFIG_PATH=$HOME/sr/lib/pkgconfig cmake . -DCMAKE_INSTALL_PREFIX:string=$HOME/sr && make install'''
</small>
</small>


Line 96: Line 136:
  $ '''LD_LIBRARY_PATH=$HOME/sr/lib G_SLICE=always-malloc G_DEBUG=gc-friendly valgrind -v --tool=memcheck --leak-check=full \'''
  $ '''LD_LIBRARY_PATH=$HOME/sr/lib G_SLICE=always-malloc G_DEBUG=gc-friendly valgrind -v --tool=memcheck --leak-check=full \'''
   '''--num-callers=40 --track-origins=yes --leak-resolution=high --track-fds=yes --fullpath-after=. \'''
   '''--num-callers=40 --track-origins=yes --leak-resolution=high --track-fds=yes --fullpath-after=. \'''
   '''--redzone-size=64 --read-var-info=yes ~/sr/bin/sigrok-cli --help'''
   '''--read-var-info=yes ~/sr/bin/sigrok-cli --help'''
</small>
</small>


Line 107: Line 147:
* [[Current events]]
* [[Current events]]
* [[Public relations]]
* [[Public relations]]
* [[News]] (obsoleted by [http://www.sigrok.org/blog the blog])
* [[sigrok-gtk]] (GTK+ based LA GUI, currently not actively maintained)
* [[sigrok-qt]] (Qt based LA GUI, currently not actively maintained)
[[Category:APIs]]

Revision as of 16:38, 31 January 2016

This page contains documentation and resources for aspiring sigrok developers.

Source code browser

Tutorials and API descriptions

Development guidelines

Please check the respective sub-project's HACKING file for coding guidelines and development tips.

Design pages

This is a list of pages we use while working through new features or designs. They are working documents, not official API or feature documentation.

Debugging

If you would like to see the output of the sr_dbg() or sr_err() functions you can use one of the following sigrok-cli options:

$ export SIGROK_DEBUG=1

or

$ sigrok-cli -l 5 <options> 

The 5 above is the log level. The following levels are available:

  • 0: no output at all
  • 1: error messages
  • 2: warnings (the default)
  • 3: informational messages
  • 4: debug
  • 5: spew

Temporarily build PulseView with clang

$ cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ .

PulseView and GDB

PulseView can be a bit tricky to debug as running it in GDB can stall the entire X11 session when PulseView crashes. This can be worked around, however. One approach is running GDB with a script that automatically creates a backtrace and terminates GDB (and thus, PulseView):

$ gdb --command=auto_bt.gdb build/bin/pulseview

with auto_bt.gdb containing lines as these:

run -l 5
thread apply all bt
quit

Another approach is to run gdb in tmux. When X11 freezes you can switch to a different virtual console, reattach to tmux, and continue the debugging process from there. This approach also makes it easier to use breakpoints.

Valgrind

The following instructions outline how you can use valgrind to help find memory-related bugs in the sigrok libraries and frontends.

Debug packages setup (optional):

In order to get more useful output from valgrind you can (optionally) install various -dbg packages (if your distro provides them).

Example for libsigrok / libsigrokdecode / sigrok-cli on Debian:

$ apt-get install libgcc1-dbg libpcre3-dbg libglib2.0-0-dbg libftdi1-dbg zlib1g-dbg libasound2-dbg python3-dbg valgrind-dbg

For Qt and/or Boost based frontends (e.g. PulseView) additional packages might be helpful in some cases:

$ apt-get install libboost1.50-dbg libqt4-dbg libstdc++6-4.7-dbg libaudiofile-dbg \
  libsm6-dbg libice6-dbg libxt6-dbg libicu48-dbg libjpeg62-dbg

Building:

Here's a short overview of how to build the sigrok subprojects for use with valgrind. Basically everything should be built with -g O0 (enable debug output, and disable compiler optimizations). In this example, everything is installed into a custom install directory ($HOME/sr) in order to have a clean and consistent environment.

$ cd libsigrok; CFLAGS="-g -O0" ./configure --prefix=$HOME/sr && make install
$ cd libsigrokdecode; CFLAGS="-g -O0" ./configure --prefix=$HOME/sr && make install
$ cd sigrok-cli; CFLAGS="-g -O0" PKG_CONFIG_PATH=$HOME/sr/lib/pkgconfig ./configure --prefix=$HOME/sr && make install
$ cd pulseview; CXXFLAGS="-g -O0" PKG_CONFIG_PATH=$HOME/sr/lib/pkgconfig cmake . -DCMAKE_INSTALL_PREFIX:string=$HOME/sr && make install

Usage:

You can now run valgrind with your preferred options against the tools/libs in $HOME/sr. Note that G_SLICE=always-malloc G_DEBUG=gc-friendly should be used to get valgrind-friendly glib behaviour.

Different command-line options, attached hardware and so on, will test different code paths in the libs/tools (e.g. sigrok-cli), of course.

$ LD_LIBRARY_PATH=$HOME/sr/lib G_SLICE=always-malloc G_DEBUG=gc-friendly valgrind -v --tool=memcheck --leak-check=full \
  --num-callers=40 --track-origins=yes --leak-resolution=high --track-fds=yes --fullpath-after=. \
  --read-var-info=yes ~/sr/bin/sigrok-cli --help

Release process

See Release process.

Miscellaneous