aboutsummaryrefslogtreecommitdiff
path: root/build2/b.cli
blob: a34e336079c6583bc090ea67a3ac2b3b85ea55c9 (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
// 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 build driver"

namespace build2
{
  {
    "<options> <variable> <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 default to
     the default operation of this meta-operation. For \cb{perform} that would
     be \cb{update}. Finally, if <target> is omitted, then it default 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 clean update     # perform(clean(./) update(./))
     b configure update # configure(?(./)) perform(update(./))
     \

     Noice the question mark used to denote the 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 operation 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 clean}(...)'
     b '{clean test clean}(...)'
     b '{clean disfigure}(...)'    # similar to distclean
     \

     For each <target> the driver expects to find a \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 \c{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 persistent configuration. 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 only need to specify \cb{src_base} explicitly once,
     during configuration. For example, a typical usage would be:

     \
     b foo/
     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 build-in and pre-defined meta-operations.

     \dl|

     \li|\cb{perform}

         Perform an operation.|

     \li|\cb{configure}

         Configure all operations in a project. Implemented by the \cb{config}
         module.|

     \li|\cb{disfigure}

         Disfigure all operations in a project. Implemented by the \cb{config}
         module.|

     \li|\cb{dist}

         Prepare a distribution for all operations in a project. Implemented
         by the \cb{dist} module.||

     \cb{build2} has the following build-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
     \c{build2} <variables>. This is normally used to pass 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 beeing 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.||"
    };

    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 it with
  '\cb{~}'. It is also made available to the buildfiles as the \cb{build.home}
  variable.
  "
}