aboutsummaryrefslogtreecommitdiff
path: root/build2/b.cli
blob: 414c3c1a0e9b9274eafe830b34ca2504f5ba7a49 (plain)
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
// file      : build2/options.cli
// copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
// license   : MIT; see accompanying LICENSE file

include <build2/types>;

"\section=1"
"\name=b"
"\summary=build2 driver"

namespace build2
{
  {
    "<options> <variables> <buildspec>
     <meta-operation> <operation> <target> <src-base>",

    "\h|SYNOPSIS|

     \cb{b --help}\n
     \cb{b --version}\n
     \c{\b{b} [<options>] [<variables>] [<buildspec>]}

     \h|DESCRIPTION|

     The \cb{build2} driver performs a set of meta-operations on operations on
     targets according to the build specification, or <buildspec> for short.
     The buildspec has the following form:

     \c{<meta-operation>(<operation>...(<target>...))...}

     All three components can be omitted. If <meta-operation> is omitted, then
     it defaults to \cb{perform}. If <operation> is omitted, then it defaults
     to the default operation for this meta-operation. For \cb{perform} it is
     \cb{update}. Finally, if <target> is omitted, then it defaults to the
     current directory. For example:

     \
     b                    # perform(update(./))
     b foo/               # perform(update(foo/))
     b foo/ bar/          # perform(update(foo/ bar/))
     b update             # perform(update(./))
     b 'clean(../)'       # perform(clean(../))
     b perform            # perform(update(./))
     b configure          # configure(?(./))
     b 'configure(../)'   # configure(?(../))
     b clean update       # perform(clean(./) update(./))
     b configure update   # configure(?(./)) perform(update(./))
     \

     Notice the question mark used to show the (imaginary) default operation
     for the \cb{configure} meta-operation. For \cb{configure} the default
     operation is \"all operations\". That is, it will configure all the
     operations for the specified target.

     You can also \"generate\" multiple operations for the same set of targets.
     Compare:

     \
     b 'clean(foo/ bar/)' 'update(foo/ bar/)'
     b '{clean update}(foo/ bar/)'
     \

     Some more useful buildspec examples:

     \
     b '{clean update}(...)'        # rebuild
     b '{clean update clean}(...)'  # make sure builds
     b '{clean test clean}(...)'    # make sure passes tests
     b '{clean disfigure}(...)'     # similar to distclean
     \

     For each <target> the driver expects to find \cb{buildfile} either in the
     target's directory or, if the directory is part of the \cb{out} tree
     (\cb{out_base}), in the corresponding \cb{src} directory (\cb{src_base}).

     For example, assuming \cb{foo/} is the source directory of a project:

     \
     b foo/              # out_base=src_base=foo/
     b foo-out/          # out_base=foo-out/ src_base=foo/
     b foo-out/exe{foo}  # out_base=foo-out/ src_base=foo/
     \

     In the above example, we assumed that the \cb{build2} driver was able to
     determine the association between \cb{out_base} and \cb{src_base}. This is
     achieved in one of two ways: the \cb{config} module (which implements the
     \cb{configure} and \cb{disfigure} meta-operations) saves this association
     as part of the configuration process. If, however, the association hasn't
     been saved, then we have to specify \cb{src_base} explicitly using the
     following extended <target> syntax:

     \c{<src-base>/@<target>}

     Continuing with the previous example:

     \
     b foo/@foo-out/exe{foo}  # out_base=foo-out/ src_base=foo/
     \

     Normally, you would need to specify \cb{src_base} explicitly only once,
     during configuration. For example, a typical usage would be:

     \
     b 'configure(foo/@foo-out/)'  # src_base is saved
     b foo-out/                    # no need to specify src_base
     b 'clean(foo-out/exe{foo})'   # no need to specify src_base
     \

     \cb{build2} has the following built-in and pre-defined meta-operations:

     \dl|

     \li|\cb{perform}

         Perform an operation.|

     \li|\cb{configure}

         Configure all operations supported by a project and save the result
         in the project's \cb{build2/config.build} file. Implemented by the
         \cb{config} module.|

     \li|\cb{disfigure}

         Disfigure all operations supported by a project and remove the
         project's \cb{build2/config.build} file. Implemented by the
         \cb{config} module.|

     \li|\cb{dist}

         Prepare a distribution containing all files necessary to perform all
         operations in a project. Implemented by the \cb{dist} module.||

     \cb{build2} has the following built-in and pre-defined operations:

     \dl|

     \li|\cb{update}

         Update a target.|

     \li|\cb{clean}

         Clean a target.|

     \li|\cb{test}

         Test a target. Performs \cb{update} as a pre-operation. Implemented by
         the \cb{test} module.|

     \li|\cb{install}

         Install a target. Performs \cb{update} as a pre-operation. Implemented
         by the \cb{install} module.||

     Before <buildspec> (but after <options>) you can set one or more
     \cb{build2} <variables>. This is normally used to specify the
     configuration values, for example:

     \
     b config.cxx=clang++ config.cxx.coptions=-O3 \
       config.install.root=/usr/local config.install.root.sudo=sudo \
       configure
     \
     "
  }

  class options
  {
    "\h|OPTIONS|"

    bool -v
    {
      "Print actual commands being executed. This is equivalent to
       \cb{--verbose 2}."
    }

    bool -q
    {
      "Run quietly, only printing error messages. This is equivalent to
       \cb{--verbose 0}."
    }

    std::uint16_t --verbose = 1
    {
      "<level>",
      "Set the diagnostics verbosity to <level> between 0 and 6. Level 0
       disables any non-error messages while level 6 produces lots of
       information, with level 1 being the default. The following additional
       types of diagnostics are produced at each level:

       \ol|

       \li|High-level information messages.|

       \li|Essential underlying commands being executed.|

       \li|All underlying commands being executed.|

       \li|Information that could be helpful to the user.|

       \li|Information that could be helpful to the developer.|

       \li|Even more detailed information, including state dumps.||"
    }

    string --pager // String to allow empty value.
    {
      "<path>",
      "The pager program to be used to show long text. Commonly used pager
       programs are \cb{less} and \cb{more}. You can also specify additional
       options that should be passed to the pager program with
       \cb{--pager-option}. If an empty string is specified as the pager
       program, then no pager will be used. If the pager program is not
       explicitly specified, then \cb{b} will try to use \cb{less}. If it
       is not available, then no pager will be used."
    }

    strings --pager-option
    {
      "<opt>",
      "Additional option to be passed to the pager program. See \cb{--pager}
       for more information on the pager program. Repeat this option to
       specify multiple pager options."
    }

    bool --help {"Print usage information and exit."}
    bool --version {"Print version and exit."}
  };

  "\h|EXIT STATUS|

  Non-zero exit status is returned in case of an error.
  "

  "\h|ENVIRONMENT|

  The \cb{HOME} environment variable is used to determine the user's home
  directory. If it is not set, then \cb{getpwuid(3)} is used instead. This
  value is used to shorten paths printed in diagnostics by replacing the home
  directory with \cb{~/}. It is also made available to \cb{buildfile}'s as the
  \cb{build.home} variable.
  "
}