Qbs Manual | Module Item

Qbs 1.10.1

Group Item ◦ Parameter Item

# Module Item

A `Module` item is a collection of properties and language items that are used for building a product if the product has a dependency on the module. The following (somewhat artificial) module pre-processes text files by removing certain characters from them. The module's name is txt_processor.

      import qbs
      import qbs.FileInfo
      import qbs.TextFile

      Module {
          property stringList unwantedCharacters: []
          FileTagger {
              patterns: ["*.raw"]
              fileTags: ["raw-txt"]
          }
          Rule {
              inputs: ["raw-txt"]
              Artifact {
                  filePath: FileInfo.relativePath(input.filePath, product.sourceDirectory) +
                             "/" + input.fileName + ".processed"
                  fileTags: ["processed-txt"]
              }
              prepare: {
                  var cmd = new JavaScriptCommand();
                  cmd.description = "Processing " + input.fileName;
                  cmd.sourceCode = function() {
                      var inFile = new TextFile(input.filePath, TextFile.ReadOnly);
                      var content = inFile.readAll();
                      inFile.close();
                      var unwantedChars = product.txt_processor.unwantedCharacters;
                      for (var c in unwantedChars)
                          content = content.replace(unwantedChars[c], "");
                      var outFile = new TextFile(output.filePath, TextFile.WriteOnly);
                      outFile.write(content);
                      outFile.close();
                  };
                  return cmd;
              }
          }
      }

And this is how a product would use the module:

      Product {
          type: "processed-txt"
          Depends { name: "txt_processor" }
          txt_processor.unwantedCharacters: ["\r"]
          files: [
              "file1.raw",
              "file2.raw"
          ]
      }

Of course, normally the pre-processed files would not be the target artifacts of the product, but rather serve as inputs to a different rule that will often come from a different module.

How you make your own modules available to Qbs is explained here.

## Special Property Values

For every property defined in a module, Qbs provides the following special built-in values:

### `base`

This value is useful when making use of inheritance. It stands for the value of the respective property in the item one level up in the inheritance chain. For instance:

      Product { // defined in MyProduct.qbs
          Depends { name: "mymodule" }
          mymodule.someProperty: ["value1"]
      }
      ------ some other file ------
      MyProduct {
          mymodule.someProperty: base.concat(["value2"]) // => ["value1", "value2"]
      }

### `original`

This is the value of the property in the module itself (possibly overridden from a profile or the command line). Use it to set a module property conditionally:

      Module { // This is mymodule
          property string aProperty: "z"
      }
      ----------
      Product {
          Depends { name: "mymodule" }
          Depends { name: "myothermodule" }
          mymodule.aProperty: myothermodule.anotherProperty === "x" ? "y" : original // => "y" if myothermodule.anotherProperty is "x", "z" otherwise

### `outer`

This value is used in nested items, where it refers to the value of the respective property in the surrounding item. It is only valid in groups and Properties items:

      Product {
          Depends { name: "mymodule" }
          mymodule.someProperty: ["value1"]
          Group {
              name: "special files"
              files: ["somefile1", "somefile2"]
              mymodule.someProperty: outer.concat(["value"]) // => ["value1", "value2"]
          }
      }

## Dependency Parameters

Modules can declare dependency parameters. Those parameters can be set within `Depends` items. Rules of the module can read the parameters of dependencies and act accordingly.

In the following example, the module foo declares the parameter `ignore`. A dependency to `bar` then sets the parameter `foo.ignore` to `true`. A rule in `foo` ignores all dependencies that have `foo.ignore` set to true.

      Module {    // Definition of module 'foo'.
          Parameter { property bool ignore }
          Rule {
              ...
              prepare: {
                  for (i in product.dependencies) {
                      var dep = product.dependencies[i];
                      if (dep.foo.ignore)
                          continue;
                      // Do something with the dependency.
                  }
              }
          }
          ...
      }
      ----------
      Product {
          Depends { name: "foo" }
          Depends { name: "bar"; foo.ignore: true }
      }

## Module Properties

Property | Type | Default | Description
--- | --- | --- | ---
additionalProductTypes | string list | empty list | The elements of this list will be added to the `type` property of a product that has a dependency on the module.
condition | bool | `true` | Controls whether the module is enabled. If this property is `false`, the surrounding `Module` item will not be considered in the module look-up.
present | bool | `true` | This property is read-only. Its value is `false` if and only if the respective `Depends` item had its `required` property set to `false` and the module was not found.
priority | int | `0` | Defines the priority of this module instance. If there is more than one module instance available for a module name, then the module with the highest priority is chosen.
setupBuildEnvironment | script | `undefined` | Script for setting up the environment in which the project is built. Use the `putEnv`, `getEnv`, and `unsetEnv` functions to alter the environment. The return value of this script is ignored.
setupRunEnvironment | script | `setupBuildEnvironment` | Script for setting up the environment in which the project is run.
validate | script | `undefined` | Script that is run after the module is loaded. It can be used to check property values and throw errors in unexpected cases. The return value is ignored.
version | string | `undefined` | The module's version. It consists of integer values separated by dots. You can check for specific values of this property in a Depends item.

Group Item ◦ Parameter Item