toolchains.rst 4.57 KB
Newer Older
André Anjos's avatar
André Anjos committed
1
.. vim: set fileencoding=utf-8 :
André Anjos's avatar
André Anjos committed
2

3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
.. Copyright (c) 2016 Idiap Research Institute, http://www.idiap.ch/          ..
.. Contact: beat.support@idiap.ch                                             ..
..                                                                            ..
.. This file is part of the beat.cmdline module of the BEAT platform.         ..
..                                                                            ..
.. Commercial License Usage                                                   ..
.. Licensees holding valid commercial BEAT licenses may use this file in      ..
.. accordance with the terms contained in a written agreement between you     ..
.. and Idiap. For further information contact tto@idiap.ch                    ..
..                                                                            ..
.. Alternatively, this file may be used under the terms of the GNU Affero     ..
.. Public License version 3 as published by the Free Software and appearing   ..
.. in the file LICENSE.AGPL included in the packaging of this file.           ..
.. The BEAT platform is distributed in the hope that it will be useful, but   ..
.. WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY ..
.. or FITNESS FOR A PARTICULAR PURPOSE.                                       ..
..                                                                            ..
.. You should have received a copy of the GNU Affero Public License along     ..
.. with the BEAT platform. If not, see http://www.gnu.org/licenses/.          ..
André Anjos's avatar
André Anjos committed
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123


Toolchains
----------

The commands available for toolchains are:

.. command-output:: ./bin/beat toolchains --help
   :cwd: ..


.. _beat-core-toolchains-checkscript:

How to check that a toolchain is correctly declared?
....................................................

To check that a toolchain declaration file is correctly written, the command
line tool can be used.

For example, we check a correct file (found in
``src/beat.core/beat/core/test/toolchains/integers_addition.json``):

.. code-block:: sh

    $ ./bin/beat --prefix=src/beat.core/beat/core/test/ toolchains check \
      integers_addition
    The toolchain is executable!

Here, the ``--prefix`` option is used to tell the scripts where all our data
formats, toolchains and algorithms are located, and ``integers_addition`` is the
name of the toolchain we want to check (note that we don't add the ``.json``
extension, as this is the name of the toolchain, not the filename!).

Now we check a file that isn't a correctly formatted JSON file:

``src/beat.core/beat/core/test/toolchains/invalid/invalid.json``:

.. code-block:: json

    {
        "invalid": true,
    }

.. code-block:: sh

    $ ./bin/beat --prefix=src/beat.core/beat/core/test/ toolchains check \
      invalid/invalid
    The toolchain isn't valid, due to the following errors:
        Failed to decode the JSON file 'beat/src/beat.core/beat/core/test/toolchains/invalid/invalid.json':
            Expecting property name enclosed in double quotes: line 3 column 1 (char 23)

Here we are told that something is wrong JSON-wise around the line 3, column 1
of the JSON file. The error is the ``,`` (comma) character: in JSON, the last
field of an object (``{}``) or the last element of an array (``[]``) cannot be
followed by a comma.  This is the corrected version:

.. code-block:: json

    {
        "invalid": true
    }

Also note that since we tell the script that all our toolchain declaration
files are located in ``src/beat.core/beat/core/test/toolchains/``, the
subfolders in that location are considered as part of the name of the data
formats they contains (like here ``invalid/invalid``).

As a last example, here is the result of the script when the toolchain
references unknown inputs and outputs (see the following sections for
explanations about the content of the declaration file):

``src/beat.core/beat/core/test/toolchains/invalid/empty_blocks_list.json``:

.. code-block:: json

    {
        "blocks": [],
        "databases": [ {
                "name": "integers",
                "outputs": {
                    "values": "single_integer"
                }
            }
        ],
        "connections": [ {
                "from": "integers.values",
                "to": "echo.in"
            }
        ],
        "results": [
            "echo.out"
        ]
    }

.. code-block:: sh

    $ ./bin/beat --prefix=src/beat.core/beat/core/test/ toolchains check \
      invalid/empty_blocks_list
    The toolchain isn't valid, due to the following errors:
        Unknown inputs: echo.in
        Unknown result outputs: echo.out