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.

Note: Module providers are an advanced concept that you will rarely need to use directly. Reading this section is not required for most people's everyday work.

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.

© 2023 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.