Qbs
Blog Documentation Get Qbs
  • Qbs Manual
  • QbsProbes
  • PathProbe
  • Qbs 2.1.1

    • Contents

    PathProbe QML Type

    Locates files outside the project. More...

    Import Statement: import QbsProbes
    Inherited By:

    BinaryProbe, FrameworkProbe, IncludeProbe, and LibraryProbe

    Properties

    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"]}
]