Qbs Quick Reference: Difference between revisions
No edit summary |
(Use syntaxhighlight tag) |
||
(21 intermediate revisions by 13 users not shown) | |||
Line 1: | Line 1: | ||
{{LangSwitch}} | |||
[[Category:Tools::qbs]] | |||
Qbs is | {{WarningBox|text=On October 29th, 2018, The Qt Company announced that Qbs is [https://blog.qt.io/blog/2018/10/29/deprecation-of-qbs/ deprecated].}} | ||
== Introduction == | |||
Qbs is the next-generation build system "initially introduced in the [https://blog.qt.io/blog/2012/02/15/introducing-qbs/ Qt Labs Blog]. This page is intended as a quick guide to porting project files from qmake '''.pro''' syntax to '''.qbs'''. It is not intended to supplant the official documentation, rather to be a quick summary of the current status of qbs functionality with a focus on how to port from qmake. | |||
Some things at the time of writing have no equivalent qbs syntax. Bugtracker links are included for missing functionality, where known. | |||
= | == Qbs Manual == | ||
The full Qbs Manual is found at http://doc.qt.io/qbs | |||
== Migrating from other build systems == | |||
For up-to-date information, see: | |||
[http://doc-snapshots.qt.io/qbs/porting-to-qbs.html#migrating-from-qmake Migrating from qmake] | |||
== | == .pro and .pri == | ||
The top-level .qbs file contains the "Project" definition. A project can contain multiple products, so you may find that multiple .pro files can be expressed in a single .qbs. The subdirs pattern will typically convert to a single .qbs containing references to multiple .qbs files. Each .qbs file would then define a single product or sub-project. | |||
.qbs files can also be used like .pri files in that a top-level .qbs can include sections defined in another .qbs. For example: | |||
<syntaxhighlight lang="qml"> | |||
/* CrazyProduct.qbs */ | |||
import qbs.base 1.0 | |||
Product { | |||
property string craziness: "low" | |||
} | |||
/* hellocrazyworld.qbs */ | |||
CrazyProduct { | |||
craziness: "enormous" | |||
name: "hellocrazyworld" | |||
// … | |||
} | |||
</syntaxhighlight> | |||
qbs | .qbs files in the same directory as the top-level .qbs file are picked up automatically. Others must be explicitly imported and named using an "import … as …" statement: | ||
<syntaxhighlight lang="qml"> | |||
import qbs.base 1.0 | |||
import "../CrazyProduct.qbs" as CrazyProduct | |||
CrazyProduct { | |||
craziness: "enormous" | |||
name: "hellocrazyworld" | |||
// … | |||
} | |||
</syntaxhighlight> | |||
It is also possible pick groups of source files externally like with .pri files, by importing a .qbs with a Group defined in it and declaring this imported group inside the Product declaration. | |||
<syntaxhighlight lang="qml"> | |||
/* external.qbs */ | |||
import qbs | |||
Group { | |||
files: ["file1.cpp", "file2.cpp"] | |||
} | |||
/* product.qbs */ | |||
import qbs | |||
import "external.qbs" as SourceGroup | |||
Product { | |||
name: "SomeProduct" | |||
SourceGroup {} | |||
} | |||
</syntaxhighlight> | |||
If opened with qtcreator, files from external.qbs will be visible in a group belonging to SomeProduct | |||
== Conditionals == | |||
Instead of the qmake syntax of "windows { … }" or "macx:…", you specify a "condition" property in the relevant block. Conditionally-compiled files should be collected in a "Group" block, while platform-specific properties should go in a "Properties" block rather than being put in the main (outer) block: | |||
<syntaxhighlight lang="qml"> | |||
Group { | |||
condition: qbs.targetOS.contains("windows") | |||
files: [ | |||
"harddiskdeleter_win.cpp", | |||
"blowupmonitor_win.cpp", | |||
"setkeyboardonfire_win.cpp" | |||
] | |||
} | |||
Properties { | |||
condition: qbs.targetOS.contains("linux") | |||
cpp.defines: outer.concat(["USE_BUILTIN_DESTRUCTORS"]) | |||
} | |||
</syntaxhighlight> | |||
See the DEFINES section above for important information about how conditionals and cpp.defines interact. | |||
== | == C++ compiler options == | ||
Here is a selection of options that are supported. The full list can be found in share/qbs/modules/cpp/CppModule.qbs in the qbs source tree, these are some of the more useful: | |||
<syntaxhighlight lang="qml"> | |||
cpp.optimization: "none" // or "fast" | |||
cpp.debugInformation: true | |||
cpp.staticLibraries: "libraryName" | |||
cpp.dynamicLibraries: "libraryName" | |||
cpp.frameworks: "frameworkName" | |||
cpp.precompiledHeader: "myheader.pch" | |||
cpp.warningLevel: "all" // or "none", "default" | |||
cpp.treatWarningsAsErrors: true | |||
cpp.cxxLanguageVersion // E.g. "c++11" | |||
</syntaxhighlight> | |||
Note that setting things like cflags directly is discouraged (because they are compiler-dependent), and higher-level alternatives like cpp.optimization: "fast" should be used if available. | |||
== | == Installing files == | ||
Create a group containing the files, and set qbs.install and qbs.installDir: | |||
<syntaxhighlight lang="qml"> | |||
Group { | |||
qbs.install: true | |||
qbs.installDir: "lib/myproj/" | |||
files: [ | |||
"Menu.qml", | |||
"SomeImportantFile.bin" | |||
] | |||
} | |||
</syntaxhighlight> | |||
For files generated by the build (e.g. an executable), you need to match them by their file tag: | |||
= | <syntaxhighlight lang="qml"> | ||
Group { | |||
qbs.install: true | |||
qbs.installDir: "bin" | |||
fileTagsFilter: "application" | |||
} | |||
</syntaxhighlight> | |||
By default, installation happens automatically when building. The default installation root is called | |||
"install_root" and is located at the top level of the build directory. It can be overwritten by setting | |||
the qbs.installRoot property on the command line. | |||
== | == Command-line examples == | ||
64-bit: | |||
=. | <syntaxhighlight lang="sh"> | ||
$ qbs -f /path/to/project.qbs --products productname qbs.architecture:x86_64 | |||
</syntaxhighlight> | |||
== "Magic" variables == | |||
= | |||
= | |||
Variables defined in various scopes, which may not be obvious: | Variables defined in various scopes, which may not be obvious: | ||
==qbs== | === qbs === | ||
This has lots of useful things in, such as: targetOS ( | This has lots of useful things in, such as: targetOS ("windows", "linux", "darwin", …); buildVariant ("debug", "release"); architecture ("x86", "x86_64", …) | ||
==project== | === project === | ||
Valid anywhere in your project, needed to refer to project properties from within a product: | Valid anywhere in your project, needed to refer to project properties from within a product: | ||
= | <syntaxhighlight lang="qml"> | ||
Project { | |||
property string version: "1.0" | |||
Product { | |||
cpp.defines: ["PROJECT_VERSION=" + project.version] | |||
} | |||
} | |||
</syntaxhighlight> | |||
== | === buildDirectory === | ||
The top-level build directory. By default will be a subdirectory in the directory where you invoked qbs from, whose name is derived from the current profile. | |||
It can also be explicitly specified via the -d option. | |||
=== Module names === | |||
Modules that are declared as dependencies can be referred to by their name and their properties accessed. For example: | |||
<syntaxhighlight lang="qml"> | |||
Product { | |||
Depends { name: "Qt.quick" } | |||
Qt.quick.qmlDebugging: false | |||
} | |||
</syntaxhighlight> |
Latest revision as of 14:18, 20 September 2021
On October 29th, 2018, The Qt Company announced that Qbs is deprecated. |
Introduction
Qbs is the next-generation build system "initially introduced in the Qt Labs Blog. This page is intended as a quick guide to porting project files from qmake .pro syntax to .qbs. It is not intended to supplant the official documentation, rather to be a quick summary of the current status of qbs functionality with a focus on how to port from qmake.
Some things at the time of writing have no equivalent qbs syntax. Bugtracker links are included for missing functionality, where known.
Qbs Manual
The full Qbs Manual is found at http://doc.qt.io/qbs
Migrating from other build systems
For up-to-date information, see:
.pro and .pri
The top-level .qbs file contains the "Project" definition. A project can contain multiple products, so you may find that multiple .pro files can be expressed in a single .qbs. The subdirs pattern will typically convert to a single .qbs containing references to multiple .qbs files. Each .qbs file would then define a single product or sub-project.
.qbs files can also be used like .pri files in that a top-level .qbs can include sections defined in another .qbs. For example:
/* CrazyProduct.qbs */
import qbs.base 1.0
Product {
property string craziness: "low"
}
/* hellocrazyworld.qbs */
CrazyProduct {
craziness: "enormous"
name: "hellocrazyworld"
// …
}
.qbs files in the same directory as the top-level .qbs file are picked up automatically. Others must be explicitly imported and named using an "import … as …" statement:
import qbs.base 1.0
import "../CrazyProduct.qbs" as CrazyProduct
CrazyProduct {
craziness: "enormous"
name: "hellocrazyworld"
// …
}
It is also possible pick groups of source files externally like with .pri files, by importing a .qbs with a Group defined in it and declaring this imported group inside the Product declaration.
/* external.qbs */
import qbs
Group {
files: ["file1.cpp", "file2.cpp"]
}
/* product.qbs */
import qbs
import "external.qbs" as SourceGroup
Product {
name: "SomeProduct"
SourceGroup {}
}
If opened with qtcreator, files from external.qbs will be visible in a group belonging to SomeProduct
Conditionals
Instead of the qmake syntax of "windows { … }" or "macx:…", you specify a "condition" property in the relevant block. Conditionally-compiled files should be collected in a "Group" block, while platform-specific properties should go in a "Properties" block rather than being put in the main (outer) block:
Group {
condition: qbs.targetOS.contains("windows")
files: [
"harddiskdeleter_win.cpp",
"blowupmonitor_win.cpp",
"setkeyboardonfire_win.cpp"
]
}
Properties {
condition: qbs.targetOS.contains("linux")
cpp.defines: outer.concat(["USE_BUILTIN_DESTRUCTORS"])
}
See the DEFINES section above for important information about how conditionals and cpp.defines interact.
C++ compiler options
Here is a selection of options that are supported. The full list can be found in share/qbs/modules/cpp/CppModule.qbs in the qbs source tree, these are some of the more useful:
cpp.optimization: "none" // or "fast"
cpp.debugInformation: true
cpp.staticLibraries: "libraryName"
cpp.dynamicLibraries: "libraryName"
cpp.frameworks: "frameworkName"
cpp.precompiledHeader: "myheader.pch"
cpp.warningLevel: "all" // or "none", "default"
cpp.treatWarningsAsErrors: true
cpp.cxxLanguageVersion // E.g. "c++11"
Note that setting things like cflags directly is discouraged (because they are compiler-dependent), and higher-level alternatives like cpp.optimization: "fast" should be used if available.
Installing files
Create a group containing the files, and set qbs.install and qbs.installDir:
Group {
qbs.install: true
qbs.installDir: "lib/myproj/"
files: [
"Menu.qml",
"SomeImportantFile.bin"
]
}
For files generated by the build (e.g. an executable), you need to match them by their file tag:
Group {
qbs.install: true
qbs.installDir: "bin"
fileTagsFilter: "application"
}
By default, installation happens automatically when building. The default installation root is called "install_root" and is located at the top level of the build directory. It can be overwritten by setting the qbs.installRoot property on the command line.
Command-line examples
64-bit:
$ qbs -f /path/to/project.qbs --products productname qbs.architecture:x86_64
"Magic" variables
Variables defined in various scopes, which may not be obvious:
qbs
This has lots of useful things in, such as: targetOS ("windows", "linux", "darwin", …); buildVariant ("debug", "release"); architecture ("x86", "x86_64", …)
project
Valid anywhere in your project, needed to refer to project properties from within a product:
Project {
property string version: "1.0"
Product {
cpp.defines: ["PROJECT_VERSION=" + project.version]
}
}
buildDirectory
The top-level build directory. By default will be a subdirectory in the directory where you invoked qbs from, whose name is derived from the current profile. It can also be explicitly specified via the -d option.
Module names
Modules that are declared as dependencies can be referred to by their name and their properties accessed. For example:
Product {
Depends { name: "Qt.quick" }
Qt.quick.qmlDebugging: false
}