summaryrefslogtreecommitdiffstats
path: root/rsb/commands.rst
blob: ab338c1f8ecba489d1070c4fa28de806c3c72bb5 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
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
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
.. comment SPDX-License-Identifier: CC-BY-SA-4.0

.. comment COPYRIGHT (c) 2012 - 2016.
.. comment Chris Johns <chrisj@rtems.org>

Commands
========

Checker (sb-check)
------------------

This commands checks your system is set up correctly. Most options are ignored::

    $ ../source-builder/sb-check --help
    sb-check: [options] [args]
    RTEMS Source Builder, an RTEMS Tools Project (c) 2012-2013 Chris Johns
    Options and arguments:
    --force                : Force the build to proceed
    --quiet                : Quiet output (not used)
    --trace                : Trace the execution
    --dry-run              : Do everything but actually run the build
    --warn-all             : Generate warnings
    --no-clean             : Do not clean up the build tree
    --always-clean         : Always clean the build tree, even with an error
    --jobs                 : Run with specified number of jobs, default: num CPUs.
    --host                 : Set the host triplet
    --build                : Set the build triplet
    --target               : Set the target triplet
    --prefix path          : Tools build prefix, ie where they are installed
    --topdir path          : Top of the build tree, default is $PWD
    --configdir path       : Path to the configuration directory, default: ./config
    --builddir path        : Path to the build directory, default: ./build
    --sourcedir path       : Path to the source directory, default: ./source
    --patchdir path        : Path to the patches directory, default: ./patches
    --tmppath path         : Path to the temp directory, default: ./tmp
    --macros file[,[file]  : Macro format files to load after the defaults
    --log file             : Log file where all build out is written too
    --url url[,url]        : URL to look for source
    --no-download          : Disable the source downloader
    --targetcflags flags   : List of C flags for the target code
    --targetcxxflags flags : List of C++ flags for the target code
    --libstdcxxflags flags : List of C++ flags to build the target libstdc++ code
    --with-<label>         : Add the --with-<label> to the build
    --without-<label>      : Add the --without-<label> to the build
    --regression           : Set --no-install, --keep-going and --always-clean
    $ ../source-builder/sb-check
    RTEMS Source Builder - Check, v0.2.0
    Environment is ok

Defaults (sb-defaults)
----------------------

This commands outputs and the default macros for your when given no
arguments. Most options are ignored::

    $ ../source-builder/sb-defaults --help
    sb-defaults: [options] [args]
    RTEMS Source Builder, an RTEMS Tools Project (c) 2012-2013 Chris Johns
    Options and arguments:
    --force                : Force the build to proceed
    --quiet                : Quiet output (not used)
    --trace                : Trace the execution
    --dry-run              : Do everything but actually run the build
    --warn-all             : Generate warnings
    --no-clean             : Do not clean up the build tree
    --always-clean         : Always clean the build tree, even with an error
    --jobs                 : Run with specified number of jobs, default: num CPUs.
    --host                 : Set the host triplet
    --build                : Set the build triplet
    --target               : Set the target triplet
    --prefix path          : Tools build prefix, ie where they are installed
    --topdir path          : Top of the build tree, default is $PWD
    --configdir path       : Path to the configuration directory, default: ./config
    --builddir path        : Path to the build directory, default: ./build
    --sourcedir path       : Path to the source directory, default: ./source
    --patchdir path        : Path to the patches directory, default: ./patches
    --tmppath path         : Path to the temp directory, default: ./tmp
    --macros file[,[file]  : Macro format files to load after the defaults
    --log file             : Log file where all build out is written too
    --url url[,url]        : URL to look for source
    --no-download          : Disable the source downloader
    --targetcflags flags   : List of C flags for the target code
    --targetcxxflags flags : List of C++ flags for the target code
    --libstdcxxflags flags : List of C++ flags to build the target libstdc++ code
    --with-<label>         : Add the --with-<label> to the build
    --without-<label>      : Add the --without-<label> to the build
    --regression           : Set --no-install, --keep-going and --always-clean

Set Builder (sb-set-builder)
----------------------------

This command builds a set::

    $ ../source-builder/sb-set-builder --help
    RTEMS Source Builder, an RTEMS Tools Project (c) 2012-2013 Chris Johns
    Options and arguments:
    --force                : Force the build to proceed
    --quiet                : Quiet output (not used)
    --trace                : Trace the execution
    --dry-run              : Do everything but actually run the build
    --warn-all             : Generate warnings
    --no-clean             : Do not clean up the build tree
    --always-clean         : Always clean the build tree, even with an error
    --regression           : Set --no-install, --keep-going and --always-clean
    ---jobs                 : Run with specified number of jobs, default: num CPUs.
    --host                 : Set the host triplet
    --build                : Set the build triplet
    --target               : Set the target triplet
    --prefix path          : Tools build prefix, ie where they are installed
    --topdir path          : Top of the build tree, default is $PWD
    --configdir path       : Path to the configuration directory, default: ./config
    --builddir path        : Path to the build directory, default: ./build
    --sourcedir path       : Path to the source directory, default: ./source
    --patchdir path        : Path to the patches directory, default: ./patches
    --tmppath path         : Path to the temp directory, default: ./tmp
    --macros file[,[file]  : Macro format files to load after the defaults
    --log file             : Log file where all build out is written too
    --url url[,url]        : URL to look for source
    --no-download          : Disable the source downloader
    --no-install           : Do not install the packages to the prefix
    --targetcflags flags   : List of C flags for the target code
    --targetcxxflags flags : List of C++ flags for the target code
    --libstdcxxflags flags : List of C++ flags to build the target libstdc++ code
    --with-<label>         : Add the --with-<label> to the build
    --without-<label>      : Add the --without-<label> to the build
    --mail-from            : Email address the report is from.
    --mail-to              : Email address to send the email too.
    --mail                 : Send email report or results.
    --smtp-host            : SMTP host to send via.
    --no-report            : Do not create a package report.
    --report-format        : The report format (text, html, asciidoc).
    --bset-tar-file        : Create a build set tar file
    --pkg-tar-files        : Create package tar files
    --list-bsets           : List available build sets
    --list-configs         : List available configurations
    --list-deps            : List the dependent files.

The ``arguments`` are a list of build sets to build.

**Options**:

``--force``:
  Force the build to proceed even if the host check fails. Typically this
  happens if executable files are found in the path at a different location to
  the host defaults.

``--trace``:
  Trace enable printing of debug information to stdout. It is really only of
  use to RTEMS Source Builder's developers.

``--dry-run``:
  Do everything but actually run the build commands. This is useful when
  checking a new configuration parses cleanly.

``--warn-all``:
  Generate warnings.

``--no-clean``:
  Do not clean up the build tree during the cleaning phase of the build. This
  leaves the source and the build output on disk so you can make changes, or
  amend or generate new patches. It also allows you to review configure type
  output such as ``config.log``.

``--always-clean``:
  Clean away the results of a build even if the build fails. This is normally
  used with ``--keep-going`` when regression testing to see which build sets
  fail to build. It keeps the disk usage down.

``--jobs``:
  Control the number of jobs make is given. The jobs can be ``none`` for only 1
  job, ``half`` so the number of jobs is half the number of detected cores, a
  fraction such as ``0.25`` so the number of jobs is a quarter of the number of
  detected cores and a number such as ``25`` which forces the number of jobs to
  that number.

``--host``:
  Set the host triplet value. Be careful with this option.

``--build``:
  Set the build triplet. Be careful with this option.

``--target``:
  Set the target triplet. Be careful with this option. This is useful if you
  have a generic configuration script that can work for a range of
  architectures.

``--prefix path``:
  Tools build prefix, ie where they are installed.

``--topdir path``:
  Top of the build tree, that is the current directory you are in.

``--configdir path``:
  Path to the configuration directory. This overrides the built in defaults.

``--builddir path``:
  Path to the build directory. This overrides the default of +build+.

``--sourcedir path``:
  Path to the source directory. This overrides the default of +source+.

``--patchdir path``:
  Path to the patches directory. This overrides the default of +patches+.

``--tmppath path``:
  Path to the temporary directory. This overrides the default of +tmp+.

``--macros files``:
  Macro files to load. The configuration directory path is searched.

``--log file``:
  Log all the output from the build process. The output is directed to +stdout+
  if no log file is provided.

``--url url``:
  URL to look for source when downloading. This is can be comma separate list.

``--no-download``:
  Disable downloading of source and patches. If the source is not found an
  error is raised.

``--targetcflags flags``:
  List of C flags for the target code. This allows for specific local
  customisation when testing new variations.

``--targetcxxflags flags``:
  List of C++ flags for the target code. This allows for specific local
  customisation when testing new variations.

``--libstdcxxflags flags``:
  List of C++ flags to build the target libstdc++ code. This allows for
  specific local customisation when testing new variations.

``--with-<label>``:
  Add the ``--with-<label>`` to the build. This can be tested for in a script
  with the ``%bconf_with`` macro.

``--without-<label>``:
  Add the ``--without-<label>`` to the build. This can be tested for in a
  script with the ``%bconf_without`` macro.

``--mail-from``:
  Set the from mail address if report mailing is enabled.

``--mail-to``:
  Set the to mail address if report mailing is enabled. The report is mailed to
  this address.

``--mail``:
  Mail the build report to the mail to address.

``--smtp-host``:
  The SMTP host to use to send the email. The default is ``localhost``.

``--no-report``:
  Do not create a report format.

``--report-format format``:
  The report format can be ``text`` or ``html``. The default is ``html``.

``--keep-going``:
  Do not stop on error. This is useful if your build sets performs a large
  number of testing related builds and there are errors.

``--always-clean``:
  Always clean the build tree even with a failure.

``--no-install``:
  Do not install the packages to the prefix. Use this if you are only after the
  tar files.

``--regression``:
  A convenience option which is the same as ``--no-install``, ``--keep-going``
  and ``--always-clean``.

``--bset-tar-file``:
  Create a build set tar file. This is a single tar file of all the packages in
  the build set.

``--pkg-tar-files``:
  Create package tar files. A tar file will be created for each package built
  in a build set.

``--list-bsets``:
  List available build sets.

``--list-configs``:
  List available configurations.

``--list-deps``:
  Print a list of dependent files used by a build set. Dependent files have a
  ``dep[?]` prefix where ``?`` is a number. The files are listed alphabetically.

Set Builder (sb-builder)
------------------------

This command builds a configuration as described in a configuration
file. Configuration files have the extension of ``.cfg``::

    $ ./source-builder/sb-builder --help
    sb-builder: [options] [args]
    RTEMS Source Builder, an RTEMS Tools Project (c) 2012 Chris Johns
    Options and arguments:
    --force                : Force the build to proceed
    --quiet                : Quiet output (not used)
    --trace                : Trace the execution
    --dry-run              : Do everything but actually run the build
    --warn-all             : Generate warnings
    --no-clean             : Do not clean up the build tree
    --always-clean         : Always clean the build tree, even with an error
    --jobs                 : Run with specified number of jobs, default: num CPUs.
    --host                 : Set the host triplet
    --build                : Set the build triplet
    --target               : Set the target triplet
    --prefix path          : Tools build prefix, ie where they are installed
    --topdir path          : Top of the build tree, default is $PWD
    --configdir path       : Path to the configuration directory, default: ./config
    --builddir path        : Path to the build directory, default: ./build
    --sourcedir path       : Path to the source directory, default: ./source
    --patchdir path        : Path to the patches directory, default: ./patches
    --tmppath path         : Path to the temp directory, default: ./tmp
    --macros file[,[file]  : Macro format files to load after the defaults
    --log file             : Log file where all build out is written too
    --url url[,url]        : URL to look for source
    --targetcflags flags   : List of C flags for the target code
    --targetcxxflags flags : List of C++ flags for the target code
    --libstdcxxflags flags : List of C++ flags to build the target libstdc++ code
    --with-<label>         : Add the --with-<label> to the build
    --without-<label>      : Add the --without-<label> to the build
    --list-configs         : List available configurations