PathProbe

Locates files outside the project. More...

Inherited By:

BinaryProbe, FrameworkProbe, IncludeProbe, and LibraryProbe

List of all members, including inherited members

Properties

allResults : varList
candidateFilter : var
candidatePaths : stringList
environmentPaths : stringList
fileName : string
filePath : string
nameFilter : script
nameSuffixes : stringList
names : stringList
path : string
pathSuffixes : stringList
platformEnvironmentPaths : stringList
platformSearchPaths : pathList
searchPaths : pathList
selectors : varList

Detailed Description

Finds files that have the specified file name suffix, such as .exe, from the specified locations.

PathProbe takes as input lists of paths to search files from and file name patterns. The paths are specified by using the environmentPaths, searchPaths, platformEnvironmentPaths and platformSearchPaths properties; the path are searched in the same order as listed. The file name patterns are specified by the names and nameSuffixes properties. Returns the first file that matches the file name patterns. If no such file is found, the probe.found property is set to false.

For example, a simple PathProbe that searches for the stdio.h header can be used as follows:

 Product {
     Depends { name: "cpp" }
     PathProbe {
         id: probe
         pathSuffixes: ["include"]
         names: ["stdio.h"]
     }
     cpp.includePaths: probe.found ? [probe.path] : []
 }

Property Documentation

allResults : varList

This property contains the list of objects, each object representing a single found file:

 {
     found: true,
     candidatePaths: ["path1/to/file", "path2/to/file", ...]
     filePath: "path/to/file"
     fileName: "file"
     path: "path/to"
 }

See also filePath, fileName, and path.

candidateFilter : var

This property holds the function that can be used to filter out unsuitable candidates. For example, when searching for a library, it might be necessary to check its architecture:

 PathProbe {
     pathSuffixes: [".so", ".dll", ".dylib"]
     candidateFilter: {
         function getLibraryArchitecture(file) { ... }
         return function(file) {
             return Utilities.isSharedLibrary(file)
                     && getLibraryArchitecture(file) == qbs.architecture;
         }
     }
 }

candidatePaths : stringList

This property contains the result list of all paths that were checked before a file was found (including the file names).

This property is set even if the Probe didn't find anything and can be used to give the user a hint what went wrong:

 Module {
     Probes.BinaryProbe {
         id: pythonProbe
         names: "python"
     }
     validate: {
         if (!pythonProbe.found) {
             throw ModUtils.ModuleError(
                     "Could not find python binary at any of the following locations:\n\t" +
                     pythonProbe.candidatePaths.join("\n\t"));
         }
     }
 }

Default: Undefined

environmentPaths : stringList

The list of environment variables that contains paths where to search files. Paths in the environment variable should be separated using FileInfo.pathListSeparator().

Default: Undefined

fileName : string

This property contains the found file's name (excluding the path).

Default: Undefined

filePath : string

This property contains the full path to the found file, including the file name.

Default: Undefined

nameFilter : script

A script that is executed for each file name before prepending file suffixes. Can be used to transform file names.

nameSuffixes : stringList

The list of file suffixes to search for. These suffixes are appended to every file name passed via the names property.

Default: Undefined

names : stringList

The list of file names to search for.

Default: Undefined

path : string

This property contains the full path where the found file is located (that is, the file directory).

Default: Undefined

pathSuffixes : stringList

A list of relative paths that are appended to each path where PathProbe searches for files. That is, the file should be located within one of the subfolders passed using this property.

Default: Undefined

platformEnvironmentPaths : stringList

The list of platform environment variables that contains paths where to search files. Paths in the environment variable should be separated using FileInfo.pathListSeparator().

Default: Undefined

platformSearchPaths : pathList

The list of platform paths where to search files.

Default: ['/usr', '/usr/local'] on Unix hosts, empty otherwise

searchPaths : pathList

The list of paths where to search files.

Default: Undefined

selectors : varList

This property should be used to search for multiple files. It contains the list of selectors each of which describes a single file to search for. A selector can be either a string, a stringList, or a dictionary.

The following example searches for three files and illustrates different ways to specify selectors:

 selectors: [
     // 1st file with a single name
     "header.h",
     // 2nd file with possible name variants
     ["config.h", "foo-config.h", "bar-config.h"],
     // 3rd file with possible name and suffix variants
     {names: ["footk", "footk-version"], nameSuffixes: [".h", ".hpp"]}
 ]

Contents

PathProbe

Properties

Detailed Description

Property Documentation