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.

Generating Microsoft Visual Studio Projects

To generate a project for another build system, such as Microsoft Visual Studio, use the qbs generate command and specify a generator using the -g option. For example:

 # For Visual Studio
 qbs generate -g visualstudio2015

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 qbs generate in order for the changes to be reflected in your IDE.

Generating IAR Embedded Workbench Projects

To generate a project for IAR Embedded Workbench, use the qbs generate command and specify a generator using the -g option. For example:

 # For IAREW v8xxxx
 qbs generate -g iarew8 profile:<your/qbs/profile>
 qbs generate -g iarew8 -d <path/to/build/directory> -f <path/to/qbs/project> profile:<your/qbs/profile>

Note: You need to specify a specific QBS profile, which is required for a generator to fetch a target architecture to generate the project.

Note: IAR EW generator creates a native target project.

Supported IAR EW generators are listed in a table below:

KEIL uVision Projects

To generate a project for KEIL uVision, use the qbs generate command and specify a generator using the -g option. For example:

 # For KEIL UV5
 qbs generate -g keiluv5 profile:<your/qbs/profile>
 qbs generate -g keiluv5 -d <path/to/build/directory> -f <path/to/qbs/project> profile:<your/qbs/profile>

Note: You need to specify a specific QBS profile, which is required for a generator to fetch a target architecture to generate the project.

Note: KEIL UV generator creates a native target project.

Supported KEIL UV generators are listed in a table below:

Generating Clang Compilation Databases

To generate a Clang compilation database (clangdb), use the following command:

 qbs generate --generator clangdb

Generating Makefiles

To generate a Makefile, use the following command:

 qbs generate --generator makefile

Targets

The generated Makefile will contain targets for all output artifacts known to Qbs.

In addition, the following targets are created for every product:

• <product-name> to build the product
• clean-<product-name> to remove all files generated by the above target
• install-<product-name> to install the product's artifacts that have qbs.install set

In the above list, the placeholder <product-name> stands for the product's name with all characters that are not ASCII letters, digits, dots or underscores replaced with underscore characters.

The special target all builds all products whose builtByDefault property is enabled. This is the default target. It is complemented by install and clean.

Note: The Makefile will not be able to build artifacts created by JavaScriptCommands, because there is no command line to run for them.

Pre-defined Variables

The build directory and the install root are set to whatever you specified when calling the generator. If you did not specify anything, Qbs' default values are used. You can override these values when invoking the make tool by explicitly setting the BUILD_ROOT and INSTALL_ROOT variables, respectively. For instance:

 $ qbs generate -g makefile config:make modules.qbs.installRoot:/opt/mydir
 $ make -f make/Makefile                                 # Will install to /opt/mydir
 $ make -f make/Makefile INSTALL_ROOT=/opt/myotherdir    # Will install to /opt/myotherdir

Spaces in Directory Names

Due to the difficulties involved in making this work correctly, Qbs will refuse to generate a Makefile if the source, build or install root directories contain spaces. It will try to handle spaces in file names of output artifacts, though.

Platform-specific Differences in Format

Qbs assumes that the Makefile will be invoked on the current host platform, so that platform's tools will be used for copying and removing files, and path separators will be converted to backslashes on Windows. When dealing with spaces in artifact names, on Unix-like systems compatibility with GNU make is assumed with regards to quoting.

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:

 Product {
     // ERROR: 'name' property cannot have different values based on the configuration
     name: qbs.configuration === "debug"
         ? "MyProduct_debug"
         : "MyProduct"
 }

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):

 Product {
     // OK
     property bool isDebug: <some value>
     name: isDebug ? "MyProduct_debug" : "MyProduct"
 }

The properties to which the limitation applies includes but is not limited to:

• Product.name
• bundle.isBundle

If a simple workaround is possible in a particular case (for example, varying Product.targetName across configuration instead of Product.name, the generator will typically suggest it in the error message.