Module Providers

There are use cases for which a pre-defined module is not flexible enough. For instance, the overall set of modules related to a certain task might depend on some information present on the local platform.

How Qbs Uses Module Providers

If Qbs encounters a Depends item whose name does not match a known module, it checks whether such a module can be generated. This procedure works as follows:

1. If the qbsModuleProviders property is not undefined, for each provider name in the list, all search paths are scanned for a file called module-providers/<name>.qbs or module-providers/<name>/provider.qbs.
2. If the qbsModuleProviders property is undefined, search paths are scanned for a file called module-providers/<name>/provider.qbs, where <name> is the name of the dependency as specified in the Depends item. Multi-component names such as "a.b" are turned into nested directories, and each of them is scanned, starting with the deepest path. For instance, if the dependency's name is a.b, then Qbs will look for a/b/provider.qbs and then a/provider.qbs.
3. If such a file is found, it needs to contain a ModuleProvider item. This item is instantiated, which potentially leads to the creation of one or more modules, and Qbs retrieves the search paths to find these modules from the item. The details are described in the ModuleProvider documentation.
4. If a matching module provider was found and provided new search paths, a second attempt will be made to locate the dependency using the new paths. The search for a matching module provider ends as soon as one was found, regardless of whether it created any modules or not.
5. If no matching module provider was found in any of the search paths, Qbs will fall back to a generic module provider, which creates a module that attempts to locate the dependency via pkg-config. This fallback mechanism can be disabled in the respective Depends item or globally via the --no-fallback-module-provider option.

Selecting Module Providers

As described above, it is possible to select which providers to run using the qbsModuleProviders property. Providers contribute to the qbsSearchPaths in the order specified by this property, so modules generated by providers specified earlier are prioritized. This property can be set on the Product as well as the Project level:

 $ qbs resolve project.qbsModuleProviders:providerA    \ # sets property globally for the Project
     projects.SomeProject.qbsModuleProviders:providerB \ # overrides property for the specific Project
     products.SomeProduct.qbsModuleProviders:providerC \ # overrides property for the specific Product

Parameterizing Module Providers

You can pass information to module providers from the command line, via profiles or from within a product, in a similar way as you would do for modules. For instance, the following invocation of Qbs passes information to two module providers a and b:

 $ qbs moduleProviders.a.p1:true moduleProviders.a.p2:true moduleProviders.b.p:false

Qbs will set the properties of the respective module providers accordingly. In the above example, module provider a needs to declare two boolean properties p1 and p2, and they will be set to true and false, respectively.