Utilities Service

The Utilities service offers miscellaneous operations.

Available Operations

builtinExtensionNames

Utilities.builtinExtensionNames(): string[]

Returns the names of all builtin JavaScript extensions (services), such as "File", "TextFile", or "Utilities".

This function was introduced in version 1.9.1.

canonicalArchitecture

Utilities.canonicalArchitecture(architecture: string): string

Returns the canonical name for the given architecture, mapping the various aliases an architecture may be known by to a single value. For example, both "x86_64" and "amd64" map to "x86_64". An empty input yields an empty string.

See qbs.architecture.

This function was introduced in version 1.2.

canonicalPlatform

Utilities.canonicalPlatform(platform: string): string[]

Returns the list of canonical operating system identifiers for the given platform name. For example, canonicalPlatform("macos") returns ["macos", "darwin", "bsd", "unix"]. These are the same values the qbs.targetOS property is populated with; see Relation between targetPlatform and targetOS for the full mapping.

This function was introduced in version 1.11.

canonicalTargetArchitecture

Utilities.canonicalTargetArchitecture(architecture: string,
                                      endianness?: string,
                                      vendor?: string,
                                      system?: string,
                                      abi?: string): string

Returns the canonical target architecture string built from the given components. Only architecture is required; the remaining arguments (endianness, vendor, system, and abi) are optional and default to an empty string.

This function was introduced in version 1.7.1.

canonicalToolchain

Utilities.canonicalToolchain(...toolchain: string): string[]

Expands the given toolchain name (or names) into the full, canonically ordered toolchain list. For example, canonicalToolchain("clang") returns ["clang", "llvm", "gcc"].

See qbs.toolchain.

This function was introduced in version 1.6.

certificateInfo

Utilities.certificateInfo(certificateData): object

Returns the properties of the given DER-encoded certificate as an object.

clangClCompilerInfo

Utilities.clangClCompilerInfo(compilerFilePath: string,
                              architecture: string,
                              vcvarsallPath: string,
                              compilerLanguage: string,
                              sdkVersion: string): object

Returns information about the given clang-cl compiler as an object with the properties buildEnvironment and macros. The compilerLanguage argument must be either "c" or "cpp".

cStringQuote

Utilities.cStringQuote(str: string): string

Takes a string and escapes special characters in a way that the result is suitable for use as a C/C++ string literal. This function is typically used to specify values for cpp.defines.

This function was introduced in version 1.8.

getArchitecturesFromBinary

Utilities.getArchitecturesFromBinary(path: string): string[]

Returns the list of architectures contained in the given Mach-O file, fat binary, or static archive.

getHash

Utilities.getHash(key: string): string

Calculates a 16-byte hash of the input and returns it. Rules in modules should use this function to find unique locations for output artifacts in the build directory without duplicating the whole directory structure of the respective input file (to deal with the case of two files with the same name in different subdirectories of the same product).

This function was introduced in version 1.4.

getNativeSetting

Utilities.getNativeSetting(filePath: string, key?: string, defaultValue?: var): var

Reads a value from a native settings store: the Windows registry, a macOS property list, or an INI file, depending on filePath. If key is omitted, the default value of the store is read. Returns defaultValue (or undefined) if the requested entry does not exist.

This function was introduced in version 1.2.

installedClangCls

Utilities.installedClangCls(path: string): object[]

Returns a list of the clang-cl compilers found under the given path.

installedMSVCs

Utilities.installedMSVCs(preferredArchitecture?: string): object[]

Returns a list of the installed MSVC toolchains. If preferredArchitecture is given, the result is restricted to toolchains targeting that architecture; otherwise the host architecture is used.

isSharedLibrary

Utilities.isSharedLibrary(fileName: string): boolean

Returns true if the given file name denotes a shared library according to the platform's naming conventions, and false otherwise.

This function was introduced in version 1.13.

kernelVersion

Utilities.kernelVersion(): string

Returns the version of the host operating system's kernel.

This function was introduced in version 1.8.

msvcCompilerInfo

Utilities.msvcCompilerInfo(compilerFilePath: string,
                           compilerLanguage: string,
                           sdkVersion: string): object

Returns information about the given MSVC compiler as an object with the properties buildEnvironment and macros. The compilerLanguage argument must be either "c" or "cpp".

nativeSettingGroups

Utilities.nativeSettingGroups(filePath: string): string[]

Returns the top-level groups of the native settings store identified by filePath. See also getNativeSetting.

This function was introduced in version 1.5.

qmlTypeInfo

Utilities.qmlTypeInfo(): string

Returns QML type information about the qbs language items. This is primarily intended for use by tooling, such as IDEs.

This function was introduced in version 1.9.1.

rfc1034Identifier

Utilities.rfc1034Identifier(str: string): string

Returns an RFC-1034 compliant identifier based on the given string by replacing each character that is not Latin alphanumeric or . with -.

This function was introduced in version 1.0.

signingIdentities

Utilities.signingIdentities(): object

Returns a map of the code-signing identities available on the host.

smimeMessageContent

Utilities.smimeMessageContent(filePath: string): string

Returns the decoded content of the S/MIME message located at filePath, or undefined if the file cannot be read. A provisioning profile is an S/MIME message whose content is an XML property list, so this operation can be used to read such files.

versionCompare

Utilities.versionCompare(version1: string, version2: string): number

Interprets the two arguments as version numbers and returns a number that is smaller than, equal to, or greater than zero if version1 is smaller than, equal to, or greater than version2, respectively.

The version strings consist of up to three numbers separated by dots.

This function was introduced in version 1.6.