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
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
|
/****************************************************************************
**
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of Qbs.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/
// **********************************************************************
// NOTE: the sections are not ordered by their logical order to avoid
// reshuffling the file each time the index order changes (i.e., often).
// Run the fixnavi.pl script to adjust the links to the index order.
// **********************************************************************
/*!
\contentspage{index.html}{Qbs}
\page index.html
\nextpage overview.html
\title Qbs Manual
\section1 Version \qbsversion
\QBS is a tool that helps simplify the build process for
developing projects across multiple platforms. \QBS can be used for any
software project, regardless of programming language, toolkit, or libraries used.
\note Please report bugs and suggestions to the
\l{http://bugreports.qt.io/}{Qt Bug Tracker}.
\list
\li \l{Introduction}
\li \l{Setup}
\list
\li \l{Installing}
\li \l{Configuring}
\li \l{Managing Qt Versions}
\endlist
\li \l{Usage}
\list
\li \l{Language Introduction}
\li \l{Building Applications}
\li \l{Running Applications}
\li \l{Installing Files}
\li \l{Using the Shell}
\li \l{Generators}
\li \l{Custom Modules and Items}
\endlist
\li \l{How-tos}
\li \l{Reference}
\list
\li \l{List of All Items}
\list
\li \l{List of Language Items}
\li \l{List of Convenience Items}
\endlist
\li \l{List of Built-in Services}
\li \l{List of Command-line Tools}
\li \l{List of Modules}
\li \l{Command and JavaScriptCommand}
\endlist
\li \l{Appendix A: Building Qbs}
\li \l{Appendix B: Code Attributions}
\endlist
*/
/*!
\contentspage index.html
\previouspage index.html
\page overview.html
\nextpage setup.html
\title Introduction
\QBS is a build automation tool designed to conveniently manage the build
process of real-life software projects across multiple platforms. It
provides the following benefits:
\list
\li Declarative paradigm
\li Well-defined language
\li Platform and programming language independence
\li Correct and fast incremental builds
\li Extensible architecture
\li Easy integration to IDEs
\endlist
\section1 Declarative Paradigm
When writing a project, it is important to describe the build tasks and
dependencies between them, rather than the build order. It is difficult to
determine the correct build order in complex projects, especially during
parallel builds. The build tool should bear that burden, not the developer.
With a declarative language, \QBS enables you to express intent rather than
specifying single build steps. This provides the appropriate level of
abstraction for a build system. For example, \e dependencies can be created
between \e products, such that the target \e artifacts of the dependency
can be used as input to the build \e rules in the context of the depending
product. In addition, you can \e export dependencies and \e properties to
other products.
\QBS is modular with clean interfaces between modules. A \e module is a
collection of properties and \e {language items} that are used for
building a product if the product depends on the module. The properties
that can be set for a module are used to control the behavior of the
toolchain used to build the module.
\QBS itself knows nothing about file types or extensions, and therefore all
source files in a product are handled equally. However, you can assign
\e {file tags} to an artifact to act as markers or to specify a file type.
\QBS applies a rule to the source files of the project and chooses the
ones that match the input file tags specified by the rule. It then creates
artifacts in the build graph that have other filenames and file tags.
Products and projects can contain \e probes that are run prior to building,
for instance to locate dependent headers, libraries, and other files outside
the project directory.
\section1 Well-Defined Language
\QBS projects are specified in a QML dialect. QML is a concise, easy to
learn, and intuitive language that is used successfully in the Qt project.
Its core is declarative, but it can be extended with JavaScript snippets
for extra flexibility.
\QBS builds applications based on the information in a project file. Each
project file specifies one \l{Project Item}{project} that can contain
several \l{Product Item}{products}. You specify the type of the product,
such as an \e application, and the dependencies the product has on other
products.
The product type determines the set of \l{Rule Item}{rules} that \QBS
applies to produce artifacts from input files. The input files can be
divided into \l{Group Item}{groups} according to their type or purpose, for
example. A group can also be used to attach \l{Properties Item}{properties}
to products.
The following is an example of a minimal project file that specifies the
product type, application name, source file, and a dependency on the
\l{Module cpp}{cpp module}:
\code
import qbs
Application {
name: "helloworld"
files: "main.cpp"
Depends { name: "cpp" }
}
\endcode
For more information, see \l{Language Introduction}.
\section1 Platform and Programming Language Independence
\QBS can be used for any software project, regardless of programming
language, toolkit, or libraries used. \QBS has built-in support for
building applications for Windows, Linux, macOS, Android, iOS, tvOS,
watchOS, QNX, and FreeBSD, as well as for cross-compilation. It can be
easily extended to support further platforms.
Invoking \c {qbs build} from the command line automatically builds the
project for the current host platform using the best available toolchain and
settings, unless a default profile is set. You can configure additional
profiles for each toolchain you want to use and select the profile to use
at build time.
For example, to build applications for Android devices, you would need to
set up a profile for the Android toolchain and select it when you build the
application. If you name the profile \e Android, you would then enter the
following command:
\code
qbs build profile:Android
\endcode
For more information, see \l{Building Applications}.
Platform and programming language support is implemented as a set of
\l{List of Modules}{modules} that your product depends on. In the language
example above, the dependency on the \l{Module cpp}{cpp module} determines
that the C++ sources are compiled and linked into a binary.
Alternatively, you could use the \l{CppApplication Item}{CppApplication}
convenience item that implies a dependency on the \c cpp module:
\code
CppApplication {
name: "helloworld"
files: "main.cpp"
}
\endcode
Additionally, if the sources use Qt, you need a dependency to the
\l{Qt Modules}{Qt.core module}, and so on.
In addition to building projects, \QBS can install the build artifacts to
a location from where they can be run on the desktop or on a device. \QBS
modules can be used to create installers for the end users of the
applications. For example, the \l{Module dmg}{dmg} module contains
properties and rules for building Apple Disk Images, which are typically
used to distribute applications and installers on macOS. The
\l{Module innosetup}{innosetup}, \l{Module nsis}{nsis}, and \l{Module wix}
{wix} modules contain properties and rules for building installers for
Windows platforms.
\section1 Correct and Fast Incremental Builds
\QBS is an all-in-one tool that generates a build graph from a high-level
project description (like qmake or CMake) and additionally undertakes the
task of executing the commands in the low-level build graph (like make).
\QBS automatically takes advantage of multi-processor and multi-core systems
to achieve maximum build parallelization. By default, running \c qbs without
any arguments is roughly equivalent to running \c {make -j<n>} where \c n is
the number of CPU cores. Similarly, \QBS allows the number of concurrent
jobs to be explicitly specified using its own \c -j option.
\QBS has knowledge about the whole project, and therefore builds remain
correct even when you build sub-projects, because \QBS ensures that all
dependencies are built too. This virtually eliminates the need for clean
builds.
\QBS uses dynamic build graphs with build rules that can generate a variable
number of files and that are executed only when needed. When figuring out
which rules to execute, \QBS starts at the product type and then looks for
a way to produce artifacts with matching file tags from source files, using
a chain of rules that are connected by their respective input and output
tags. For an example of how rules are applied when building products, see
\l{Rules and Product Types}.
The \QBS build rules can produce a variable number of outputs.
If the input changes, only the required rules are applied at build time.
If a rule is applied, all the dependent rules are applied as well, but only
those. This feature ensures the correctness of the build graph after source
code changes without having to re-configure the whole project.
Changing properties that do not affect the build, because they are not used
by rules, will not cause the project to be rebuilt. The use of properties is
tracked. Generated artifacts that cease to exist are deleted to avoid
picking outdated generated artifacts and indefinitely increasing the size of
the build directory.
Fast incremental builds are crucial for a fast edit-build-run cycle.
Instead of retrieving the timestamps of generated files, \QBS uses the time
stamps stored in the build graph. This is especially important on Windows,
where file system operations are slow.
If the project files were not changed, the build graph is loaded from disk.
It is stored in a binary format that can be loaded much faster than the real
project files. The project files are parsed only if they were changed.
\section1 Extensible Architecture
You can create your own custom \l{List of Modules}{modules} and
\l{List of Language Items}{items} and make \QBS aware of them.
You store the custom modules and items in a subdirectory of the project
directory and specify the path to the subdirectory as a value of the
\c qbsSearchPaths property. For example, if the custom module is located at
\c my-modules/modules/modulename/modulename.qbs, you would specify it in the
project file as follows:
\code
Project {
qbsSearchPaths: "my-modules"
\endcode
For more information, see \l{Custom Modules and Items}.
\section1 IDE Integration
\QBS can be used not only from the command line, but also in combination
with an IDE, such as Qt Creator, Microsoft Visual Studio, or Xcode.
Qt Creator directly supports \QBS projects. Visual Studio and Xcode users
can use \QBS to generate Microsoft Visual Studio and Xcode projects.
For more information, see \l {Generators}.
\section2 Qt Creator
\l{http://doc.qt.io/qtcreator/index.html}{Qt Creator} uses the same \QBS
library as the \QBS command line tools. Therefore, it can retrieve all the
information required to build a single file or project through a defined
public API. Qt Creator provides accurate information about the build
progress and displays a project tree that reflects the logical structure of
the project, instead of presenting low-level information, such as the file
system structure. Adding or removing source files keeps the existing project
file structure intact.
For more information about using \QBS to build projects from Qt Creator, see
\l{http://doc.qt.io/qtcreator/creator-project-qbs.html}{Setting Up Qbs}.
*/
/*!
\contentspage index.html
\previouspage overview.html
\page setup.html
\nextpage installing.html
\title Setup
\list
\li \l{Installing}
\li \l{Configuring}
\li \l{Managing Qt Versions}
\endlist
*/
/*!
\contentspage index.html
\previouspage reference.html
\page building-qbs.html
\nextpage attributions.html
\title Appendix A: Building Qbs
\QBS can be \l{Installing}{installed from binary packages} or built from
sources, as described in this appendix. In addition, this appendix describes
how to use Docker images for developing \QBS.
\section1 Supported Platforms
\QBS can be installed and run on the following platforms:
\list
\li Windows 7, or later
\li Linux (tested on Debian 8 and 9, Ubuntu 16.04, OpenSuSE 13.2, and
Arch Linux)
\li macOS 10.7, or later
\endlist
\section1 System Requirements
To build \QBS from the source, you need:
\list
\li Qt 5.6.2, or later
\li Windows: MinGW with GCC 4.9 or Microsoft Visual Studio 2015,
or later
\li Linux: GCC 4.9, or later, or Clang 3.9.0, or later
\li macOS: Xcode 6.2, or later
\endlist
An installed toolchain has to match the one that Qt was compiled with.
\section1 Building
To build \QBS, enter the following command:
\code
qmake -r qbs.pro && make
\endcode
Depending on your platform, you might use \c mingw32-make, \c nmake, or
\c jom instead of \c make.
Installation by using \c {make install} is usually not needed. It is however
possible, by entering the following command.
\code
make install INSTALL_ROOT=$INSTALL_DIRECTORY
\endcode
\section1 Configure Options
\QBS recognizes the following qmake CONFIG options to customize the build:
\table
\header \li Option \li Notes
\row \li qbs_enable_unit_tests \li Enable additional autotests.
\row \li qbs_disable_rpath \li Disable the use of rpath. This can be used when packaging
\QBS for distributions which do not permit the use of rpath,
such as Fedora.
\row \li qbs_no_dev_install \li Exclude header files from installation, that is, perform a
non-developer build.
\row \li qbs_no_man_install \li Exclude the man page from installation.
\row \li qbs_enable_project_file_updates \li Enable API for updating project files. This
implies a dependency to the Qt GUI module.
\endtable
\section1 Using Docker
A set of Docker images for developing \QBS (which are maintained by the \QBS team) is available
\l{https://hub.docker.com/u/qbsbuild/}{on Docker Hub}.
Both Windows Server Core and Debian Linux container types are available.
\note The source code for the \QBS development Docker images is located in the \c{docker/}
directory of the \QBS source tree, if you wish to build them yourself.
\section2 Linux Containers
The easiest way to get started is to build \QBS using a Linux container. These types of
containers are supported out of the box on all the supported host platforms: Windows, macOS,
and Linux. Run the following to download the \QBS development image based on Debian 9
\e Stretch:
\code
docker pull qbsbuild/qbsdev:stretch
\endcode
You can then create a new container with the \QBS source directory mounted from your host
machine's file system, by running:
\code
docker run -it -v $PWD:/qbs -w /qbs qbsbuild/qbsdev:stretch
\endcode
Or with a slightly different syntax for Windows:
\code
docker run -it -v %CD%:/qbs -w /qbs qbsbuild/qbsdev:stretch
\endcode
You will now be in an interactive Linux shell where you can develop and build \QBS.
\section2 Windows Containers
To build \QBS for Windows using Windows containers, your host OS must be running Windows 10 Pro
and have Hyper-V enabled. \l{https://docs.docker.com/docker-for-windows/#switch-between-windows-and-linux-containers}{Switch your Docker environment to use Windows containers}, then run the
following command to download the Windows 10 \QBS development image:
\code
docker pull qbsbuild/qbsdev:windowsservercore
\endcode
You can then create a new container with the \QBS source directory mounted from your host
machine's file system, by running:
\code
docker run -it -v %CD%:C:\qbs -w C:\qbs qbsbuild/qbsdev:windowsservercore
\endcode
If you want to use Windows containers on a macOS or Linux host, you will have to create a
virtual machine running Windows 10 and register it with \c{docker-machine}. There is at least
\l{https://github.com/StefanScherer/windows-docker-machine}{one Open Source project}
that helps to facilitate this by using using Packer, Vagrant, and VirtualBox.
The \c{docker run} command to spawn a Windows container on a Unix host will look slightly
different (assuming \c windows is the name of the Docker machine associated with the Windows
container hosting VM):
\code
eval $(docker-machine env windows)
docker run -it -v C:$PWD:C:\\qbs -w C:\\qbs qbsbuild/qbsdev:windowsservercore
\endcode
\section2 Building Release Packages
Release packages for \QBS for Windows can be built using the following command on Windows:
\code
docker run --rm -v %CD%:C:\qbs -w C:\qbs qbsbuild/qbsdev:windowsservercore cmd /c scripts\make-release-archives
\endcode
For building release packages for Windows on macOS or Linux:
\code
eval $(docker-machine env windows)
docker run --rm -v C:$PWD:C:\\qbs -w C:\\qbs qbsbuild/qbsdev:windowsservercore cmd /c scripts\\make-release-archives
\endcode
*/
/*!
\contentspage index.html
\previouspage setup.html
\page installing.html
\nextpage configuring.html
\title Installing
\QBS binaries are available for Windows, macOS, Linux, and FreeBSD.
On all platforms, \QBS binaries are part of the \l{Qt Creator} and \l{Qt SDK}
installers. You can find the \c qbs executable in the \c bin directory of
Qt Creator, or within the application bundle's \c MacOS directory on macOS.
\QBS can also be built locally from sources. For more information, see
\l{Appendix A: Building Qbs}.
\section1 Windows
The Qt Project provides prebuilt binaries for Windows (x86 and x64) at
\l{https://download.qt.io/official_releases/qbs/}. For commercial customers of
The Qt Company, the binaries are available in the \l {Qt Account}.
The binaries are packaged in a .zip folder that can be extracted to a location
of your choice.
\QBS is also available as a \l Chocolatey package, which can be installed in
the usual way:
\code
choco install qbs
\endcode
The \c .nupkg file can also be downloaded directly from
\l{https://download.qt.io/official_releases/qbs/} for
\l{https://chocolatey.org/security#organizational-use-of-chocolatey}{offline installation}.
\section1 macOS
\QBS can be conveniently installed on macOS with the \l{MacPorts} or \l{Homebrew}
package managers:
\code
brew install qbs
\endcode
or
\code
port install qbs
\endcode
\section1 Linux and FreeBSD
\QBS is \l{https://repology.org/metapackage/qbs/versions}{available via the
package management systems} of Linux distributions, and FreeBSD.
*/
/*!
\contentspage index.html
\previouspage installing.html
\page configuring.html
\nextpage qt-versions.html
\title Configuring
Open a build shell (on Windows open an MSVC command prompt,
on other platforms you can usually open the default shell):
\code
qbs setup-toolchains --detect
\endcode
The tool chain detector automatically sets up a profile for each detected tool chain.
You can list the existing profiles by running:
\code
qbs config --list profiles
\endcode
Now you should be ready to build your first project with \QBS.
Go into examples/helloworld-minimal and type:
\code
qbs profile:<profile name>
\endcode
If you want to build projects that use Qt, additional steps are necessary. Please refer to
\l{Managing Qt Versions} for more information.
*/
/*!
\contentspage index.html
\previouspage configuring.html
\page qt-versions.html
\nextpage usage.html
\title Managing Qt Versions
\section1 Introduction
To let \QBS know where the Qt build or Qt version is that you want to use,
you must register it.
Register a Qt version like this:
\code
qbs setup-qt /usr/bin/qmake myqt
\endcode
This will create the \c myqt profile which can then be used on
the command line:
\code
qbs profile:myqt
\endcode
\note If the \c setup-toolchains command has found more than one toolchain, you will need
to manually link your Qt profile to one of them, like this:
\code
qbs config profiles.myqt.baseProfile <profile name>
\endcode
\section1 Multiple Qt Builds
To support multiple Qt builds, or in fact any combination of related settings, you need to
create several profiles. The following example illustrates how to set up
three different profiles, each for a different Qt build:
\code
qbs setup-qt ~/dev/qt/4.7/bin/qmake qt47
qbs setup-qt ~/dev/qt/4.8/bin/qmake qt48
qbs setup-qt ~/dev/qt/5.0/qtbase/bin/qmake qt5
\endcode
You can set the default Qt build like this:
\code
qbs config defaultProfile qt5
\endcode
To choose a Qt build that is different from the default, use:
\code
qbs build profile:qt48
\endcode
You can set other properties in a profile (not just Qt ones), in the same way
you override them from the command line. For example:
\code
qbs setup-qt C:\Qt\5.0.0\qtbase\bin\qmake.exe qt5
qbs config profiles.qt5.qbs.architecture x86_64
qbs config profiles.qt5.baseProfile msvc2010
\endcode
The last example uses the inheritance feature of profiles. All settings in the profile
set as \c baseProfile are known in the derived profile as well.
They can of course be overridden there.
*/
/*!
\contentspage index.html
\previouspage qt-versions.html
\page usage.html
\nextpage language-introduction.html
\title Usage
\list
\li \l{Language Introduction}
\li \l{Building Applications}
\li \l{Running Applications}
\li \l{Installing Files}
\li \l{Using the Shell}
\li \l{Generators}
\li \l{Custom Modules and Items}
\endlist
*/
/*!
\contentspage index.html
\previouspage usage.html
\page language-introduction.html
\nextpage building-applications.html
\title Language Introduction
\QBS uses project files (*.qbs) to describe the contents of a project.
A project contains one or more \l{Product Item}{products}. A product is the target of a build
process, typically an application, library or maybe a tar ball.
\note \QBS source files are assumed to be UTF-8 encoded.
\section1 The Obligatory Hello World Example
\QBS project files are written using a QML dialect.
A very simple C++ hello world project looks like this:
\code
---helloworld.qbs---
import qbs 1.0
Application {
name: "helloworld"
files: "main.cpp"
Depends { name: "cpp" }
}
\endcode
The import statement gives us access to some built-in types and specifies the
used language version.
\a Application describes the product we want to build. In this case, an
application. This is just a shortcut for writing
\code
Product {
type: "application"
// ...
}
\endcode
The \a name is the name of the product. In this case it is also the
name of the produced executable (on Windows, the ".exe" extension is added by default).
In the property \a files, we specify the source files for our product.
Unlike QML, the right-hand side can be either a string or a string list.
A single string is converted to a stringlist containing just one element.
So we could have also written
\code
files: [ "main.cpp" ]
\endcode
\a Depends adds the dependency to the module \l{Module cpp}{cpp}. This is necessary to let \QBS know that
we have a C++ project and want to compile main.cpp with a C++ compiler. For more information
about \QBS modules, see \l{Modules}.
\section1 Reusing Project File Code
QML-like inheritance works also in \QBS.
\code
---CrazyProduct.qbs---
import qbs 1.0
Product {
property string craziness: "low"
}
---hellocrazyworld.qbs---
import "CrazyProduct.qbs" as CrazyProduct
CrazyProduct {
craziness: "enormous"
name: "hellocrazyworld"
// ...
}
\endcode
You can put JS code into separate \c{.js} files and then import them.
\code
---helpers.js---
function planetsCorrectlyAligned()
{
// implementation
}
---myproject.qbs---
import qbs 1.0
import "helpers.js" as Helpers
Product {
name: "myproject"
Group {
condition: Helpers.planetsCorrectlyAligned()
file: "magic_hack.cpp"
}
// ...
}
\endcode
\section1 Modules
A \e module is a collection of properties and language items that are used for
building a product if the product depends on (or loads) the module.
For example, the \a cpp module looks like this (simplified):
\code
Module {
name: "cpp"
property string warningLevel
property string optimization
property bool debugInformation
property pathList includePaths
// ...
FileTagger {
patterns: "*.cpp"
fileTags: ["cpp"]
}
Rule {...} // compiler
Rule {...} // application linker
Rule {...} // static lib linker
Rule {...} // dynamic lib linker
}
\endcode
The properties that can be set for the \a cpp module are used to control the behavior of
your C++ tool chain.
In addition, you can use FileTaggers and Rules that are explained later.
As soon as your product depends on a module, it can set the properties of the
module. You specify the optimization level for your product (and all build variants) like this:
\code ---helloworld.qbs---
import qbs 1.0
Application {
name: "helloworld"
files: ["main.cpp"]
cpp.optimization: "ludicrousSpeed"
Depends { name: "cpp" }
}
\endcode
A module can implicitly depend on other modules. For example, the \c Qt.core module depends
on \c{cpp}. But to set the properties of a module you must make the dependency explicit.
\code
// THIS DOES NOT WORK
Application {
name: "helloworld"
files: ["main.cpp"]
Depends { name: "Qt.core" }
cpp.optimization: "ludicrousSpeed"
// ERROR! We do not know about "cpp" here,
// though "Qt.core" depends on "cpp".
}
// THIS WORKS
Application {
name: "helloworld"
files: ["main.cpp"]
Depends { name: "Qt.core" }
Depends { name: "cpp" }
cpp.optimization: "ludicrousSpeed"
}
\endcode
\section2 Different Properties for a Single File
Not only the product, but all the source files of the product can have their own
set of module properties. For example, assume you have some files that are known to crash
your compiler if you turn on optimizations. You want to turn off
optimizations for just these files and this is how you do it:
\code
Application {
name: "helloworld"
files: "main.cpp"
Group {
files: ["bad_file.cpp", "other_bad_file.cpp"]
cpp.optimization: "none"
}
Depends { name: "cpp" }
}
\endcode
\section2 Selecting Files by Properties
Sometimes you have a file that is only going to be compiled on a certain platform.
This is how you do it:
\code
Group {
condition: qbs.targetOS.contains("windows")
files: [
"harddiskdeleter_win.cpp",
"blowupmonitor_win.cpp",
"setkeyboardonfire_win.cpp"
]
}
Group {
condition: qbs.targetOS.contains("linux")
files: [
"harddiskdeleter_linux.cpp",
"blowupmonitor_linux.cpp",
"setkeyboardonfire_linux.cpp"
]
}
\endcode
In the above example, \a qbs.targetOS is a property of the \a target of the the \a qbs
module. The \a qbs module is always implicitly loaded. Its main properties
are:
\table
\header
\li Property
\li Type
\li Default
\li Description
\row
\li buildVariant
\li string
\li "debug"
\li Name of the current build variant. By default, "debug" and "release"
are valid values but the user can add more in a project file.
\row
\li hostOS
\li stringlist
\li platform-dependent
\li The host operating system.
May contain "windows", "linux", "macos", "darwin", "unix", etc.
\note Do not confuse this with the \c{qbs.targetOS} property, which represents the
operating system on which the binaries produced by \QBS will run.
\row
\li targetOS
\li stringlist
\li platform-dependent
\li The target operating system.
May contain "windows", "linux", "macos", "darwin", "unix",
"ios", "android", "qnx", etc.
\endtable
You can set these properties on the command line or by using a profile.
\code
$ qbs # qbs.buildVariant:debug, profile:<default profile> (or profile:none, if no default profile exists)
$ qbs release # qbs.buildVariant:release, profile:<default profile>
$ qbs debug release # builds two configurations of the project
$ qbs profile:none # all module properties have their default values
\endcode
To select files by build variant:
\code
Group {
condition: qbs.buildVariant == "debug"
files: "debughelper.cpp"
}
\endcode
To set properties for a build variant:
\code
Properties {
condition: qbs.buildVariant == "debug"
cpp.debugInformation: true
cpp.optimization: "none"
}
\endcode
Or, to use a more QML-like style:
\code
cpp.debugInformation: qbs.buildVariant == "debug" ? true : false
cpp.optimization: qbs.buildVariant == "debug" ? "none" : "fast"
\endcode
\section1 Property Types
While properties in \QBS generally work the same way as in QML, the set of possible property
types has been adapted to reflect the specific needs of a build tool. The supported types
are as follows:
\table
\header
\li Property type
\li Example
\li Description
\row
\li \c bool
\li \c{property bool someBoolean: false}
\li The usual boolean values.
\row
\li \c int
\li \c{property int theAnswer: 42}
\li Integral numbers.
\row
\li \c path
\li \c{property path aFile: "file.txt"}
\li File paths resolved relative to the directory the product they are associated with
is located in.
\row
\li \c pathList
\li \c{property pathList twoFiles: ["file1.txt", "./file2.txt"]}
\li A list of \c path values.
\row
\li \c string
\li \c{property string parentalAdvisory: "explicit lyrics"}
\li JavaScript strings.
\row
\li \c stringList
\li \c{property stringList realWorldExample: ["no", "not really"]}
\li A list of JavaScript strings.
\row
\li \c var
\li \c{property var aMap: ({ key1: "value1", key2: "value2" })}
\li Generic data, as in QML.
\endtable
\section1 Overriding Property Values from the Command Line
Property values set in project files or profiles can be overridden on the command line.
The syntax is \c{<prefix>.<prop-name>:<prop-value>}. The following command lines
demonstrate how to set different kinds of properties:
\code
$ qbs projects.someProject.projectProperty:false # set a property of a project
$ qbs products.someProduct.productProperty:false # set a property of a product
$ qbs modules.cpp.treatWarningsAsErrors:true # set a module property for all products
$ qbs products.someProduct.cpp.treatWarningsAsErrors:true # set a module property for one product
\endcode
Property values on the command line can also be expressed in JavaScript form, the same way
as you would write them in a project file. Make sure to take care of proper
quoting, so that the shell does not interpret any of the values itself. Properties of type
\c stringList can also be provided as comma-separated values, if none of the strings contain
special characters:
\code
$ qbs projects.someProject.listProp:'["a", "b", "c"]'
$ qbs projects.someProject.listProp:a,b,c # same as above
$ qbs projects.someProject.listProp:'["a b", "c"]' # no CSV equivalent
\endcode
\section1 File Tags and Taggers
\QBS itself knows nothing about C++ files or file extensions. All source files
in a product are handled equally. However, you can assign \a{file tags} to an artifact
to act as a marker or to specify a file type.
An artifact can have multiple file tags.
For example, you can use the \a Group item to group files with the same file tags (or a set of
properties).
\code
Product {
Group {
files: ["file1.cpp", "file2.cpp"]
fileTags: ["cpp"]
}
Group {
files: "mydsl_scanner.l"
fileTags: ["flex", "foobar"]
}
// ...
}
\endcode
When you load the \a cpp module, you also load the following item:
\code
FileTagger {
patterns: "*.cpp"
fileTags: ["cpp"]
}
\endcode
This construct means that each source file that matches the pattern \c{*.cpp} (and
has not explicitly set a file tag) gets the file tag \c{cpp}.
The above example can be simplified to
\code
Product {
Depends: "cpp"
files: ["file1.cpp", "file2.cpp"]
Group {
files: "mydsl_scanner.l"
fileTags: ["flex", "foobar"]
}
// ...
}
\endcode
The \a FileTagger from the \a cpp module automatically assigns the \c cpp
file tag to the source files. Groups that just contain the \a files
property can be more simply expressed by using the \a files property of the product.
File tags are used by \a rules to transform one type of artifact into
another. For instance, the C++ compiler rule transforms artifacts with the file tag
\c cpp to artifacts with the file tag \c{obj}.
In addition, it is possible to use file taggers to tag files and specify custom file tags:
\code
Product {
Depends: "cpp"
Group {
overrideTags: false // The overrideTags property defaults to true.
fileTags: ["foobar"]
files: ["main.cpp"] // Gets the file tag "cpp" through a FileTagger item and
// "foobar" from this group's fileTags property.
}
// ...
}
\endcode
\section1 Rules
\QBS applies a \e rule to a pool of artifacts (in the beginning it is just the set of
source files of the project) and chooses the ones that match the input file
tags specified by the rule. Then it creates output artifacts in the build graph that have other
filenames and file tags. It also creates a script that transforms the input artifacts into the
output artifacts. Artifacts created by one rule can (and typically do) serve as inputs to
another rule. In this way, rules are connected to one another via their input and output
file tags.
For examples of rules, see the share/qbs/modules directory in the \QBS
repository.
You can define rules in your own module to be provided along with
your project. Or you can put a rule directly into your project file.
For more information, see \l{Rule Item}.
*/
/*!
\contentspage index.html
\previouspage language-introduction.html
\page building-applications.html
\nextpage running-applications.html
\title Building Applications
To build applications from the command line, enter the following commands:
\code
cd examples/collidingmice
qbs
\endcode
By default, \QBS uses all the CPU cores available to achieve maximum build
parallelization. To explicitly specify the number of concurrent jobs, use
the \c -j option. For example, to run 4 concurrent jobs, enter the following
command:
\code
qbs -j4
\endcode
The application is built using the default build profile that is set up
in your \QBS configuration.
You can use the \c config command to set the max number of jobs per profile.
For example, to set four jobs as the default option for a profile named
\e Android, enter the following command:
\code
qbs config profiles.Android.preferences.jobs 4
\endcode
To build with other profiles than the default one, specify options for the
build command. For example, to build debug and release configurations with
the \e Android profile, enter the following command:
\code
qbs build profile:Android debug release
\endcode
The position of the property assignment is important. In the example
above, the profile property is set for all build configurations that come
afterwards.
To set a property just for one build configuration, place the assignment after
the build configuration name.
In the following example, the property \c cpp.treatWarningsAsErrors is
set to \c true for debug only and \c cpp.optimization is set to
\c small for release only.
\code
qbs build debug modules.cpp.treatWarningsAsErrors:true release modules.cpp.optimization:small
\endcode
*/
/*!
\contentspage index.html
\previouspage running-applications.html
\page installing-files.html
\nextpage shell.html
\title Installing Files
To install your project, specify the necessary information in the project file:
\code
Application {
Group {
name: "Runtime resources"
files: "*.qml"
qbs.install: true
qbs.installDir: "share/myproject"
}
Group {
name: "The App itself"
fileTagsFilter: "application"
qbs.install: true
qbs.installDir: "bin"
}
}
\endcode
In this example, we want to install a couple of QML files and an executable.
The actual installation is then done like this (using the default profile):
\code
qbs --clean-install-root qbs.installRoot:/tmp/myProjectRoot
\endcode
Here, we want the installDir properties from the project file to be interpreted relative
to the directory \c{/tmp/myProjectRoot}, and we want that directory to be removed first.
If the \c{qbs.installRoot} property is not given, a default is used, namely
\c{<build root>/install-root}.
*/
/*!
\contentspage index.html
\previouspage building-applications.html
\page running-applications.html
\nextpage installing-files.html
\title Running Applications
By default, running an application also builds it and installs it to a
location from where it can be run on the desktop or on a device.
For example, entering the following command runs the Qt Creator application:
\code
qbs run --products qtcreator
\endcode
This command also builds and installs the product, if necessary.
*/
/*!
\contentspage index.html
\previouspage installing-files.html
\page shell.html
\nextpage generators.html
\title Using the Shell
To use the \QBS shell, enter the following command:
\code
qbs shell
\endcode
This is mainly a debugging tool. It opens a shell with the same environment that qbs uses
when building the project, so you can, for example, inspect which environment variables
will be set up.
*/
/*!
\contentspage index.html
\previouspage generators.html
\page custom-modules.html
\nextpage howtos.html
\title Custom Modules and Items
Users of \QBS are not limited to the pre-defined \l{List of Modules}{modules} and
\l{List of Language Items}{items}, they can also create their own. Here we describe how
to set up custom modules and items so that \QBS will find them.
\section1 File System Layout
Items and modules are located under a common base directory, whose name and location is
completely arbitrary. We will refer to it as \c search-path here. This directory has two
subdirectories \c modules and \c imports, which contain \QBS modules and items, respectively.
\section1 Custom Modules
To introduce a custom module \c mymodule, create a directory \c{search-path/modules/mymodule/}.
\note Module names are case-sensitive, and this also goes for the corresponding directory name.
Then, put a file containing an instance of the \l{Module Item} in there and give it the \c{.qbs}
extension. This module will be pulled in if a
\l{Product Item}{product} declares a \l{Depends Item}{dependency} on \c mymodule.
\section1 Custom Items
To introduce a custom item \c MyItem, create the file \c{search-path/imports/MyItem.qbs}.
\section1 Making \QBS Aware of Custom Modules and Items
To be able to use your custom modules and items, you need to make them known to \QBS. You can
do this per project or globally.
\section2 Project-specific Modules and Items
Let's assume you have a project that is located in \c{project_dir} and you have created some
modules in \c{project_dir/custom-stuff/modules/} as well as some items in
\c{project_dir/custom-stuff/imports/} that you want to use in the project.
To achieve this, your top-level project file should look like this:
\code
// ...
Project {
// ..
qbsSearchPaths: "custom-stuff"
// ..
}
\endcode
\note For technical reasons, the custom modules and items will not be available in the file
that contains the \c qbsSearchPaths property. Any product that wants
to make use of them needs to be in a different file that is pulled in
via the \c references property, for example. This is not a serious limitation, since
every well-structured project will be split up in this manner.
\section2 Making Custom Modules and Items Available Across Projects
What if your modules and items are generally useful and you want to access them in several
projects? In this case, it's best to add the location to your preferences. For example:
\code
qbs config preferences.qbsSearchPaths /usr/local/share/custom-qbs-extensions
\endcode
*/
/*!
\contentspage index.html
\previouspage shell.html
\page generators.html
\nextpage custom-modules.html
\title Generators
Generators are a \QBS sub-tool and set of APIs that enable arbitrary
processing to be performed on the build graph. Currently, they are used to
integrate \QBS with popular IDEs, such as Microsoft Visual Studio, and to
generate Clang compilation databases.
\section1 Generating Projects
To generate a project for another build system, such as Microsoft Visual Studio, use the
\c qbs-generate sub-command and specify a generator using the \c{-g} option. For example:
\code
# For Visual Studio
qbs generate -g visualstudio2015
\endcode
\QBS will then generate a series of files in the current directory, based on the generator that
was chosen. The resulting project files can be opened in the respective IDE
and all work can be performed there.
The project files will expose as much information as possible to the IDE and will use \QBS to
perform the actual build.
\note You cannot modify build system files and expect the changes
to be reflected in \QBS; you must edit your \QBS project files and re-run \c{qbs-generate} in
order for the changes to be reflected in your IDE.
\section1 Generating Clang Compilation Databases
To generate a \l{https://clang.llvm.org/docs/JSONCompilationDatabase.html}
{Clang compilation database (clangdb)}, use the following command:
\code
qbs generate --generator clangdb
\endcode
\section1 Limitations
Due to the high flexibility of the \QBS project format and build engine, some projects may be too
complex to produce an equivalent project file for another build system.
This list of limitations aims to be as small as possible, but one of the most notable (at least
for the Microsoft Visual Studio generator) is that certain properties must contain the same
value across all build configurations. For example, the following is not allowed:
\code
Product {
// ERROR: 'name' property cannot have different values based on the configuration
name: qbs.configuration === "debug"
? "MyProduct_debug"
: "MyProduct"
}
\endcode
\note This limitation only applies when property values are varied on the configuration
name. For example, the following is OK (as long as the value of xyz itself does not vary across
configurations):
\code
Product {
// OK
property bool isDebug: <some value>
name: isDebug ? "MyProduct_debug" : "MyProduct"
}
\endcode
The properties to which the limitation applies includes but is not limited to:
\list
\li \l{Product Item}{Product}.name
\li \l{Module bundle}{bundle}.isBundle
\endlist
If a simple workaround is possible in a particular case (for example,
varying \c Product.targetName across configuration instead of
\c Product.name), the generator will typically suggest it in the error
message.
*/
/*!
\contentspage index.html
\previouspage building-qbs.html
\page attributions.html
\title Appendix B: Code Attributions
\QBS contains third-party code, which we gratefully acknowledge:
\generatelist{groupsbymodule attributions-qbs}
*/
|