miller: Add a few test-cases.
[sigrok-test.git] / 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 troubleshoot a specific test, try:
75
76     * Run all tests under decoder/test/<testroot>:
77
78       ./decoder/pdtest -v -d -r <testroot>
79   
80     * Run the named test. Note, in this case <testname> is not
81       a file but rather a test described in <testroot>/test.conf.
82
83       ./decoder/pdtest -v -d -r <testroot>/<testname>
84
85     * Print parameters as parsed from <testroot>/test.conf (to spot typos):
86
87       ./decoder/pdtest -v -s <testroot>
88
89
90 Copyright and license
91 ---------------------
92
93 sigrok-test contains various tools that are licensed under different terms.
94
95 Some are licensed under the terms of the GNU GPL version 2 (or later),
96 others under the terms of the GNU GPL version 3 (or later).
97
98 Please see the individual source files for the full list of copyright holders
99 and the license that applies to the respective tool.
100
101
102 Mailing list
103 ------------
104
105  https://lists.sourceforge.net/lists/listinfo/sigrok-devel
106
107
108 IRC
109 ---
110
111 You can find the sigrok developers in the #sigrok IRC channel on Freenode.
112
113
114 Website
115 -------
116
117  http://sigrok.org
118