-------------------------------------------------------------------------------
README
-------------------------------------------------------------------------------

The sigrok project aims at creating a portable, cross-platform,
Free/Libre/Open-Source signal analysis software suite that supports various
device types (such as logic analyzers, oscilloscopes, multimeters, and more).

sigrok-test is a collection of various tools and files for testing sigrok.


Status
------

Work in progress.

Distro packagers should NOT package this!


Requirements
------------

 - git
 - gcc
 - make
 - autoconf >= 2.63
 - automake >= 1.11
 - pkg-config >= 0.22
 - libglib >= 2.24.0
 - Python >= 3.2
 - libsigrok >= 0.5.0
 - libsigrokdecode >= 0.5.0
 - python3-coverage


Building and usage
------------------

Assumption: libsigrok and libsigrokdecode are installed in $HOME/sr.
If they are in a standard location instead, you don't need the
PKG_CONFIG_PATH and LD_LIBRARY_PATH below.

In order to get the sigrok-test source code and build it, run:

 $ git clone git://sigrok.org/sigrok-test
 $ cd sigrok-test
 $ ./autogen.sh
 $ PKG_CONFIG_PATH=$HOME/sr/lib/pkgconfig ./configure \
	--with-decodersdir=/path/to/decoders
 $ make

This will test the decoders located at /path/to/decoders:

 $ LD_LIBRARY_PATH=$HOME/sr/lib ./decoder/pdtest -r -v -a


Adding tests
------------

The best way to add tests is to copy one that is similar, and adjust
accordingly. Some notes:

 * In test.conf, the channel assignments must be done in a specific way:

    protocol-decoder <pdname> channel <pd_channel_name>=<#> ...

   Example:

    protocol-decoder mcs48 d0=8 d1=9 [...] a8=0 ...

   Of important note, the channels/probes are numbered from 0, regardless of
   the naming used in the capture file.

 * To initially generate the test files which have been configured in test.conf
   pdtest has to be run with the -f parameter first.

   Example:

    ./decoder/pdtest -r -v -f <testroot>

  This can also be done to update the test-cases in case of a changes in
  the protocol decoder.

 * To troubleshoot a specific test, try:

    * Run all tests under decoder/test/<testroot>:

      ./decoder/pdtest -v -d -r <testroot>

    * Run the named test. Note, in this case <testname> is not
      a file but rather a test described in <testroot>/test.conf.

      ./decoder/pdtest -v -d -r <testroot>/<testname>

    * Print parameters as parsed from <testroot>/test.conf (to spot typos):

      ./decoder/pdtest -v -s <testroot>


Copyright and license
---------------------

sigrok-test contains various tools that are licensed under different terms.

Some are licensed under the terms of the GNU GPL version 2 (or later),
others under the terms of the GNU GPL version 3 (or later).

Please see the individual source files for the full list of copyright holders
and the license that applies to the respective tool.


Mailing list
------------

 https://lists.sourceforge.net/lists/listinfo/sigrok-devel


IRC
---

You can find the sigrok developers in the #sigrok IRC channel on Libera.Chat.


Website
-------

 http://sigrok.org