SCons/Tool/qt3.xml

   1 <?xml version="1.0"?>
   2 <!--
   3 __COPYRIGHT__
   4
   5 This file is processed by the bin/SConsDoc.py module.
   6 See its __doc__ string for a discussion of the format.
   7 -->
   8
   9 <!DOCTYPE sconsdoc [
  10 <!ENTITY % scons SYSTEM '../../doc/scons.mod'>
  11 %scons;
  12 <!ENTITY % builders-mod SYSTEM '../../doc/generated/builders.mod'>
  13 %builders-mod;
  14 <!ENTITY % functions-mod SYSTEM '../../doc/generated/functions.mod'>
  15 %functions-mod;
  16 <!ENTITY % tools-mod SYSTEM '../../doc/generated/tools.mod'>
  17 %tools-mod;
  18 <!ENTITY % variables-mod SYSTEM '../../doc/generated/variables.mod'>
  19 %variables-mod;
  20 ]>
  21
  22 <sconsdoc xmlns="http://www.scons.org/dbxsd/v1.0"
  23           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  24           xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
  25
  26 <tool name="qt3">
  27 <summary>
  28 <para>
  29 Sets &consvars; for building Qt3 applications.
  30 </para>
  31
  32 <note><para>
  33 This tool is only suitable for building targeted to Qt3,
  34 which is obsolete
  35 (<emphasis>the tool is deprecated since 4.3,
  36 and was renamed to qt3 in 4.5.0.
  37 </emphasis>).
  38 There are contributed tools for Qt4 and Qt5, see
  39 <ulink url="https://github.com/SCons/scons-contrib">
  40 https://github.com/SCons/scons-contrib</ulink>.
  41 Qt4 has also passed end of life for standard support (in Dec 2015).
  42 </para></note>
  43
  44 <para>
  45 Note paths for these &consvars; are assembled
  46 using the <function>os.path.join</function> method
  47 so they will have the appropriate separator at runtime,
  48 but are listed here in the various
  49 entries only with the <literal>'/'</literal> separator
  50 for simplicity.
  51 </para>
  52
  53 <para>
  54 In addition, the &consvars;
  55 &cv-link-CPPPATH;,
  56 &cv-link-LIBPATH; and
  57 &cv-link-LIBS; may be modified
  58 and the variables
  59 &cv-link-PROGEMITTER;, &cv-link-SHLIBEMITTER; and &cv-link-LIBEMITTER;
  60 are modified. Because the build-performance is affected when using this tool,
  61 you have to explicitly specify it at Environment creation:
  62 </para>
  63
  64 <example_commands>
  65 Environment(tools=['default','qt3'])
  66 </example_commands>
  67
  68 <para>
  69 The &t-qt3; tool supports the following operations:
  70 </para>
  71
  72 <para>
  73 <emphasis role="strong">Automatic moc file generation from header files.</emphasis>
  74 You do not have to specify moc files explicitly, the tool does it for you.
  75 However, there are a few preconditions to do so: Your header file must have
  76 the same filebase as your implementation file and must stay in the same
  77 directory. It must have one of the suffixes
  78 <filename>.h</filename>,
  79 <filename>.hpp</filename>,
  80 <filename>.H</filename>,
  81 <filename>.hxx</filename>,
  82 <filename>.hh</filename>.
  83 You can turn off automatic moc file generation by setting
  84 &cv-link-QT3_AUTOSCAN; to <constant>False</constant>.
  85 See also the corresponding
  86 &b-link-Moc; Builder.
  87 </para>
  88
  89 <para>
  90 <emphasis role="strong">Automatic moc file generation from C++ files.</emphasis>
  91 As described in the Qt documentation, include the moc file at the end of
  92 the C++ file. Note that you have to include the file, which is generated
  93 by the transformation
  94 <literal>${QT3_MOCCXXPREFIX}&lt;basename&gt;${QT3_MOCCXXSUFFIX}</literal>, by default
  95 <filename>&lt;basename&gt;.mo</filename>. A warning is generated after building the moc file if you
  96 do not include the correct file. If you are using &f-link-VariantDir;, you may
  97 need to specify <parameter>duplicate=True</parameter>.
  98 You can turn off automatic moc file generation by setting &cv-QT3_AUTOSCAN; to
  99 <literal>False</literal>. See also the corresponding
 100 &b-link-Moc; Builder.
 101 </para>
 102
 103 <para>
 104 <emphasis role="strong">Automatic handling of .ui files.</emphasis>
 105 The implementation files generated from <filename>.ui</filename>
 106 files are handled much the same as yacc or lex files.
 107 Each <command>.ui</command> file given as a source of &b-link-Program;,
 108 &b-link-Library; or &b-link-SharedLibrary;
 109 will generate three files: the declaration file, the
 110 implementation file and a moc file. Because there are also generated headers,
 111 you may need to specify <parameter>duplicate=True</parameter> in calls to
 112 &f-link-VariantDir;.
 113 See also the corresponding
 114 &b-link-Uic; Builder.
 115 </para>
 116 </summary>
 117 <sets>
 118 <item>QT3DIR</item>
 119 <item>QT3_BINPATH</item>
 120 <item>QT3_CPPPATH</item>
 121 <item>QT3_LIBPATH</item>
 122 <item>QT3_MOC</item>
 123 <item>QT3_UIC</item>
 124 <item>QT3_LIB</item>
 125 <item>QT3_AUTOSCAN</item>
 126 <item>QT3_UICIMPLFLAGS</item>
 127 <item>QT3_UICDECLFLAGS</item>
 128 <item>QT3_MOCFROMHFLAGS</item>
 129 <item>QT3_MOCFROMCXXFLAGS</item>
 130 <item>QT3_UICDECLPREFIX</item>
 131 <item>QT3_UICDECLSUFFIX</item>
 132 <item>QT3_UICIMPLPREFIX</item>
 133 <item>QT3_UICIMPLSUFFIX</item>
 134 <item>QT3_MOCHPREFIX</item>
 135 <item>QT3_MOCHSUFFIX</item>
 136 <item>QT3_MOCCXXPREFIX</item>
 137 <item>QT3_MOCCXXSUFFIX</item>
 138 <item>QT3_UISUFFIX</item>
 139 <item>QT3_UICCOM</item>
 140 <item>QT3_MOCFROMHCOM</item>
 141 <item>QT3_MOCFROMCXXCOM</item>
 142 </sets>
 143 <uses>
 144 <item>QT3DIR</item>
 145 </uses>
 146 </tool>
 147
 148 <builder name="Moc">
 149 <summary>
 150 <para>
 151 Builds an output file from a <command>moc</command> input file.
 152 <command>moc</command> input files are either header files or C++ files.
 153 This builder is only available after using the
 154 tool &t-link-qt3;. See the &cv-link-QT3DIR; variable for more information.
 155 Example:
 156 </para>
 157
 158 <example_commands>
 159 env.Moc('foo.h')  # generates moc_foo.cc
 160 env.Moc('foo.cpp')  # generates foo.moc
 161 </example_commands>
 162 </summary>
 163 </builder>
 164
 165 <builder name="Uic">
 166 <summary>
 167 <para>
 168 Builds a header file, an implementation file and a moc file from an ui file.
 169 and returns the corresponding nodes in the that order.
 170 This builder is only available after using the tool &t-link-qt3;.
 171 Note: you can specify <filename>.ui</filename> files directly as source
 172 files to the &b-link-Program;,
 173 &b-link-Library; and &b-link-SharedLibrary; builders
 174 without using this builder. Using this builder lets you override the standard
 175 naming conventions (be careful: prefixes are always prepended to names of
 176 built files; if you don't want prefixes, you may set them to ``).
 177 See the &cv-link-QT3DIR; variable for more information.
 178 Example:
 179 </para>
 180
 181 <example_commands>
 182 env.Uic('foo.ui')  # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc']
 183 env.Uic(
 184     target=Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
 185     source='foo.ui'
 186 )  # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc']
 187 </example_commands>
 188 </summary>
 189 </builder>
 190
 191 <cvar name="QT3DIR">
 192 <summary>
 193 <para>
 194 The path to the Qt installation to build against.
 195 If not already set,
 196 &t-link-qt3; tool tries to obtain this from
 197 <varname>os.environ</varname>;
 198 if not found there, it tries to make a guess.
 199 </para>
 200 <para>
 201 <emphasis>Changed in 4.5.0</emphasis>: renamed from QTDIR.
 202 </para>
 203 </summary>
 204 </cvar>
 205
 206 <cvar name="QT3_AUTOSCAN">
 207 <summary>
 208 <para>
 209 Turn off scanning for mocable files. Use the &b-link-Moc; Builder to explicitly
 210 specify files to run <command>moc</command> on.
 211 </para>
 212 <para>
 213 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_AUTOSCAN.
 214 </para>
 215 </summary>
 216 </cvar>
 217
 218 <cvar name="QT3_BINPATH">
 219 <summary>
 220 <para>
 221 The path where the Qt binaries are installed.
 222 The default value is '&cv-link-QT3DIR;<filename>/bin</filename>'.
 223 </para>
 224 <para>
 225 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_BINPATH.
 226 </para>
 227 </summary>
 228 </cvar>
 229
 230 <cvar name="QT3_CPPPATH">
 231 <summary>
 232 <para>
 233 The path where the Qt header files are installed.
 234 The default value is '&cv-link-QT3DIR;/include'.
 235 Note: If you set this variable to <constant>None</constant>,
 236 the tool won't change the &cv-link-CPPPATH;
 237 construction variable.
 238 </para>
 239 <para>
 240 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_CPPPATH.
 241 </para>
 242 </summary>
 243 </cvar>
 244
 245 <cvar name="QT3_DEBUG">
 246 <summary>
 247 <para>
 248 Prints lots of debugging information while scanning for moc files.
 249 </para>
 250 <para>
 251 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_DEBUG.
 252 </para>
 253 </summary>
 254 </cvar>
 255
 256 <cvar name="QT3_LIB">
 257 <summary>
 258 <para>
 259 Default value is <literal>'qt'</literal>.
 260 You may want to set this to <literal>'qt-mt'</literal>.
 261 Note: If you set this variable to <constant>None</constant>,
 262 the tool won't change the &cv-link-LIBS; variable.
 263 </para>
 264 <para>
 265 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_LIB.
 266 </para>
 267 </summary>
 268 </cvar>
 269
 270 <cvar name="QT3_LIBPATH">
 271 <summary>
 272 <para>
 273 The path where the Qt libraries are installed.
 274 The default value is '&cv-link-QT3DIR;<filename>/lib</filename>'.
 275 Note: If you set this variable to <constant>None</constant>,
 276 the tool won't change the &cv-link-LIBPATH;
 277 construction variable.
 278 </para>
 279 <para>
 280 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_LIBPATH.
 281 </para>
 282 </summary>
 283 </cvar>
 284
 285 <cvar name="QT3_MOC">
 286 <summary>
 287 <para>
 288 Default value is '&cv-link-QT3_BINPATH;<filename>/moc</filename>'.
 289 </para>
 290 </summary>
 291 </cvar>
 292
 293 <cvar name="QT3_MOCCXXPREFIX">
 294 <summary>
 295 <para>
 296 Default value is <literal>''</literal>.
 297 Prefix for <command>moc</command> output files when source is a C++ file.
 298 </para>
 299 </summary>
 300 </cvar>
 301
 302 <cvar name="QT3_MOCCXXSUFFIX">
 303 <summary>
 304 <para>
 305 Default value is <literal>'.moc'</literal>.
 306 Suffix for <command>moc</command> output files when source is a C++ file.
 307 </para>
 308 <para>
 309 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_MOCCXXSUFFIX.
 310 </para>
 311 </summary>
 312 </cvar>
 313
 314 <cvar name="QT3_MOCFROMCXXFLAGS">
 315 <summary>
 316 <para>
 317 Default value is <literal>'-i'</literal>.
 318 These flags are passed to <command>moc</command> when moccing a C++ file.
 319 </para>
 320 <para>
 321 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_MOCFROMCXXFLAGS.
 322 </para>
 323 </summary>
 324 </cvar>
 325
 326 <cvar name="QT3_MOCFROMCXXCOM">
 327 <summary>
 328 <para>
 329 Command to generate a moc file from a C++ file.
 330 </para>
 331 <para>
 332 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_MOCFROMCXXCOM.
 333 </para>
 334 </summary>
 335 </cvar>
 336
 337 <cvar name="QT3_MOCFROMCXXCOMSTR">
 338 <summary>
 339 <para>
 340 The string displayed when generating a moc file from a C++ file.
 341 If this is not set, then &cv-link-QT3_MOCFROMCXXCOM; (the command line) is displayed.
 342 </para>
 343 <para>
 344 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_MOCFROMCXXCOMSTR.
 345 </para>
 346 </summary>
 347 </cvar>
 348
 349 <cvar name="QT3_MOCFROMHCOM">
 350 <summary>
 351 <para>
 352 Command to generate a moc file from a header.
 353 </para>
 354 <para>
 355 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_MOCFROMSHCOM.
 356 </para>
 357 </summary>
 358 </cvar>
 359
 360 <cvar name="QT3_MOCFROMHCOMSTR">
 361 <summary>
 362 <para>
 363 The string displayed when generating a moc file from a C++ file.
 364 If this is not set, then &cv-link-QT3_MOCFROMHCOM; (the command line) is displayed.
 365 </para>
 366 <para>
 367 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_MOCFROMSHCOMSTR.
 368 </para>
 369 </summary>
 370 </cvar>
 371
 372 <cvar name="QT3_MOCFROMHFLAGS">
 373 <summary>
 374 <para>
 375 Default value is <literal>''</literal>. These flags are passed to <command>moc</command>
 376 when moccing a header file.
 377 </para>
 378 <para>
 379 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_MOCFROMSHFLAGS.
 380 </para>
 381 </summary>
 382 </cvar>
 383
 384 <cvar name="QT3_MOCHPREFIX">
 385 <summary>
 386 <para>
 387 Default value is <literal>'moc_'</literal>.
 388 Prefix for <command>moc</command> output files when source is a header.
 389 </para>
 390 <para>
 391 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_MOCHPREFIX.
 392 </para>
 393 </summary>
 394 </cvar>
 395
 396 <cvar name="QT3_MOCHSUFFIX">
 397 <summary>
 398 <para>
 399 Default value is '&cv-link-CXXFILESUFFIX;'.
 400 Suffix for moc output files when source is a header.
 401 </para>
 402 <para>
 403 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_MOCHSUFFIX.
 404 </para>
 405 </summary>
 406 </cvar>
 407
 408 <cvar name="QT3_UIC">
 409 <summary>
 410 <para>
 411 Default value is '&cv-link-QT3_BINPATH;<filename>/uic</filename>'.
 412 </para>
 413 <para>
 414 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UIC.
 415 </para>
 416 </summary>
 417 </cvar>
 418
 419 <cvar name="QT3_UICCOM">
 420 <summary>
 421 <para>
 422 Command to generate header files from <filename>.ui</filename> files.
 423 </para>
 424 <para>
 425 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UICCOM.
 426 </para>
 427 </summary>
 428 </cvar>
 429
 430 <cvar name="QT3_UICCOMSTR">
 431 <summary>
 432 <para>
 433 The string displayed when generating header files from <filename>.ui</filename> files.
 434 If this is not set, then &cv-link-QT3_UICCOM; (the command line) is displayed.
 435 </para>
 436 <para>
 437 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UICCOMSTR.
 438 </para>
 439 </summary>
 440 </cvar>
 441
 442 <cvar name="QT3_UICDECLFLAGS">
 443 <summary>
 444 <para>
 445 Default value is ''. These flags are passed to <command>uic</command>
 446 when creating a header file from a <filename>.ui</filename> file.
 447 </para>
 448 <para>
 449 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UICDECLFLAGS.
 450 </para>
 451 </summary>
 452 </cvar>
 453
 454 <cvar name="QT3_UICDECLPREFIX">
 455 <summary>
 456 <para>
 457 Default value is <literal>''</literal>.
 458 Prefix for <command>uic</command> generated header files.
 459 </para>
 460 <para>
 461 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UICDECLPREFIX.
 462 </para>
 463 </summary>
 464 </cvar>
 465
 466 <cvar name="QT3_UICDECLSUFFIX">
 467 <summary>
 468 <para>
 469 Default value is <literal>'.h'</literal>.
 470 Suffix for <command>uic</command> generated header files.
 471 </para>
 472 <para>
 473 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UICDECLSUFFIX.
 474 </para>
 475 </summary>
 476 </cvar>
 477
 478 <cvar name="QT3_UICIMPLFLAGS">
 479 <summary>
 480 <para>
 481 Default value is <literal>''</literal>.
 482 These flags are passed to <command>uic</command> when creating a C++
 483 file from a <filename>.ui</filename> file.
 484 </para>
 485 <para>
 486 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UICIMPFLAGS.
 487 </para>
 488 </summary>
 489 </cvar>
 490
 491 <cvar name="QT3_UICIMPLPREFIX">
 492 <summary>
 493 <para>
 494 Default value is <literal>'uic_'</literal>.
 495 Prefix for uic generated implementation files.
 496 </para>
 497 <para>
 498 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UICIMPLPREFIX.
 499 </para>
 500 </summary>
 501 </cvar>
 502
 503 <cvar name="QT3_UICIMPLSUFFIX">
 504 <summary>
 505 <para>
 506 Default value is '&cv-link-CXXFILESUFFIX;'. Suffix for uic generated implementation
 507 files.
 508 </para>
 509 <para>
 510 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UICIMPLSUFFIX.
 511 </para>
 512 </summary>
 513 </cvar>
 514
 515 <cvar name="QT3_UISUFFIX">
 516 <summary>
 517 <para>
 518 Default value is <literal>'.ui'</literal>.
 519 Suffix of designer input files.
 520 </para>
 521 <para>
 522 <emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UISUFFIX.
 523 </para>
 524 </summary>
 525 </cvar>
 526
 527 </sconsdoc>