README

   1 -------------------------------------------------------------------------------
   2 README
   3 -------------------------------------------------------------------------------
   4
   5 The sigrok project aims at creating a portable, cross-platform,
   6 Free/Libre/Open-Source signal analysis software suite that supports various
   7 device types (such as logic analyzers, oscilloscopes, multimeters, and more).
   8
   9 sigrok-test is a collection of various tools and files for testing sigrok.
  10
  11
  12 Status
  13 ------
  14
  15 Work in progress.
  16
  17 Distro packagers should NOT package this!
  18
  19
  20 Requirements
  21 ------------
  22
  23  - git
  24  - gcc
  25  - make
  26  - autoconf >= 2.63
  27  - automake >= 1.11
  28  - pkg-config >= 0.22
  29  - libglib >= 2.24.0
  30  - Python >= 3.2
  31  - libsigrok >= 0.5.0
  32  - libsigrokdecode >= 0.5.0
  33  - python3-coverage
  34
  35
  36 Building and usage
  37 ------------------
  38
  39 Assumption: libsigrok and libsigrokdecode are installed in $HOME/sr.
  40 If they are in a standard location instead, you don't need the
  41 PKG_CONFIG_PATH and LD_LIBRARY_PATH below.
  42
  43 In order to get the sigrok-test source code and build it, run:
  44
  45  $ git clone git://sigrok.org/sigrok-test
  46  $ cd sigrok-test
  47  $ ./autogen.sh
  48  $ PKG_CONFIG_PATH=$HOME/sr/lib/pkgconfig ./configure \
  49         --with-decodersdir=/path/to/decoders
  50  $ make
  51
  52 This will test the decoders located at /path/to/decoders:
  53
  54  $ LD_LIBRARY_PATH=$HOME/sr/lib ./decoder/pdtest -r -v -a
  55
  56
  57 Adding tests
  58 ------------
  59
  60 The best way to add tests is to copy one that is similar, and adjust
  61 accordingly. Some notes:
  62
  63  * In test.conf, the channel assignments must be done in a specific way:
  64
  65     protocol-decoder <pdname> channel <pd_channel_name>=<#> ...
  66
  67    Example:
  68
  69     protocol-decoder mcs48 d0=8 d1=9 [...] a8=0 ...
  70
  71    Of important note, the channels/probes are numbered from 0, regardless of
  72    the naming used in the capture file.
  73
  74  * To initially generate the test files which have been configured in test.conf
  75    pdtest has to be run with the -f parameter first.
  76
  77    Example:
  78
  79     ./decoder/pdtest -r -v -f <testroot>
  80
  81   This can also be done to update the test-cases in case of a changes in
  82   the protocol decoder.
  83
  84  * To troubleshoot a specific test, try:
  85
  86     * Run all tests under decoder/test/<testroot>:
  87
  88       ./decoder/pdtest -v -d -r <testroot>
  89
  90     * Run the named test. Note, in this case <testname> is not
  91       a file but rather a test described in <testroot>/test.conf.
  92
  93       ./decoder/pdtest -v -d -r <testroot>/<testname>
  94
  95     * Print parameters as parsed from <testroot>/test.conf (to spot typos):
  96
  97       ./decoder/pdtest -v -s <testroot>
  98
  99
 100 Copyright and license
 101 ---------------------
 102
 103 sigrok-test contains various tools that are licensed under different terms.
 104
 105 Some are licensed under the terms of the GNU GPL version 2 (or later),
 106 others under the terms of the GNU GPL version 3 (or later).
 107
 108 Please see the individual source files for the full list of copyright holders
 109 and the license that applies to the respective tool.
 110
 111
 112 Mailing list
 113 ------------
 114
 115  https://lists.sourceforge.net/lists/listinfo/sigrok-devel
 116
 117
 118 IRC
 119 ---
 120
 121 You can find the sigrok developers in the #sigrok IRC channel on Libera.Chat.
 122
 123
 124 Website
 125 -------
 126
 127  http://sigrok.org
 128