- Qbs Manual
- Module Item
- Qbs 1.6.0

LoadableModule Item Probe 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:

    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.moduleProperty("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 often encountered in groups:

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

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

LoadableModule Item Probe Item