Qbs Manual | Generators

Qbs 1.14.0

Using the Shell ◦ Multiplexing

# 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 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 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.

Using the Shell ◦ Multiplexing