Scanner

Creates custom dependency scanners in products or modules. More...

• List of all members, including inherited members
• Scanner is part of List of All Items.

Properties

• condition : bool
• inputs : stringList
• recursive : bool
• scan : script
• scannerId : string
• searchPaths : script

Detailed Description

A Scanner item can appear inside a Module item, and allows to extract dependencies for artifacts from the artifacts' file contents. For example, this is what a scanner for "qrc" files might look like:

import qbs.Xml

Module {
  Scanner {
    inputs: 'qrc'
    scan: {
      var xml = new Xml.DomDocument(input.filePath);
      dependencies = [];
      // retrieve <file> entries from the XML document
      return dependencies;
    }
  }
}

Property Documentation

condition : bool

If true, the scanner is enabled, otherwise it does nothing.

Default: true

inputs : stringList

A list of file tags the input artifacts must match.

Default: Undefined

recursive : bool

Determines whether to scan the returned dependencies using the same scanner.

Default: false

scan : script

A script that reads the input artifact and returns either a string list with dependencies or an object.

If the return value is an array, it is interpreted as a list of dependency paths.

If the return value is an object, it may be empty or provide dependencies and/or scannerProperties. The dependencies property provides the dependency paths. The scannerProperties property is a map of custom values stored in the build graph and exposed as input.qbsScanners.<scannerId>.<propertyName> in prepare and outputArtifacts scripts (not in scan scripts). Use the separate searchPaths script to supply search paths.

The code in this script is treated as a function with the signature function(project, product, input, filePath), where input is the artifact at which the scan originated, and filePath is the currently scanned file. For non-recursive scans, filePath is always equal to input.filePath.

Default: Undefined

scannerId : string

An identifier for this scanner. For scanners declared in a module, the module name is prepended to this property to form a global scanner id used for caching scan results (for example, cpp.myScanner). For scanners declared directly in a product, the value is used as-is.

That global id must be unique within the product, including scanners coming from modules.

In prepare and outputArtifacts scripts, scanner properties are exposed via input.qbsScanners.<scannerId>.<propertyName> (use bracket notation when the id contains dots, for example input.qbsScanners["Qt.core.moc"]). They are not available on input in scan scripts; values come from the last scan stored in the build graph.

If not set explicitly, the pluginName is used for plugin-based scanners. Otherwise, a stable identifier (SHA1-hash) is derived from the scan script.

Default: Undefined

searchPaths : script

A script that returns the paths where to look for dependencies.

The code in this script is treated as a function with the signature function(project, product, input).

Default: Undefined

Rule SubProject