Replace Functions | qmake Manual

Qt 5.6 | qmake Manual | Replace Functions

Qt 5.6.2 Reference Documentation

Variables ◦ Test Functions

# Replace Functions

qmake provides functions for processing the contents of variables during the configuration process. These functions are called replace functions. Typically, they return values that you can assign to other variables. You can obtain these values by prefixing a function with the `$$` operator. Replace functions can be divided into built-in functions and function libraries.

See also Test Functions.

## Built-in Replace Functions

Basic replace functions are implemented as built-in functions.

### absolute_path(path[, base])

Returns the absolute path of `path`.

If `base` is not specified, uses the current directory as the base directory.

For example, the following call returns the string `"/home/johndoe/myproject/readme.txt"`:

      message($$absolute_path("readme.txt", "/home/johndoe/myproject"))

See also clean_path(), relative_path().

### basename(variablename)

Returns the basename of the file specified in `variablename`.

For example:

      FILE = /etc/passwd
      FILENAME = $$basename(FILE) #passwd

### cat(filename[, mode])

Returns the contents of `filename`. You can specify the following options for `mode`:

- `blob` returns the entire contents of the file as one value
- `lines` returns each line as a separate value (without line endings)
- `true` (default value) and `false` return file contents as separate values, split according to qmake value list splitting rules (as in variable assignments). If `mode` is `false`, values that contain only a newline character are inserted into the list to indicate where line breaks were in the file.

### clean_path(path)

Returns `path` with directory separators normalized (converted to "/") and redundant ones removed, and "."s and ".."s resolved (as far as possible). This function is a wrapper around QDir::cleanPath.

See also absolute_path(), relative_path(), shell_path(), system_path().

### dirname(file)

Returns the directory name part of the specified file. For example:

      FILE = /etc/X11R6/XF86Config
      DIRNAME = $$dirname(FILE) #/etc/X11R6

### enumerate_vars

Returns a list of all defined variable names.

### escape_expand(arg1 [, arg2 ..., argn])

Accepts an arbitrary number of arguments. It expands the escape sequences `\n`, `\r`, `\t` for each argument and returns the arguments as a list.

Note: If you specify the string to expand literally, you need to escape the backslashes, as illustrated by the following code snippet:

      message("First line$$escape_expand(\\n)Second line")

### find(variablename, substr)

Returns all the values in `variablename` that match the regular expression `substr`.

      MY_VAR = one two three four
      MY_VAR2 = $$join(MY_VAR, " -L", -L) -Lfive
      MY_VAR3 = $$member(MY_VAR, 2) $$find(MY_VAR, t.*)

MY_VAR2 will contain '-Lone -Ltwo -Lthree -Lfour -Lfive', and MY_VAR3 will contain 'three two three'.

### first(variablename)

Returns the first value of `variablename`.

For example, the following call returns `firstname`:

      CONTACT = firstname middlename surname phone
      message($$first(CONTACT))

See also last().

### format_number(number[, options...])

Returns `number` in the format specified by `options`. You can specify the following options:

- `ibase=n` sets the base of the input to `n`
- `obase=n` sets the base of the output to `n`
- `width=n` sets the minimum width of the output to `n`. If the output is shorter than `width`, it is padded with spaces
- `zeropad` pads the output with zeroes instead of spaces
- `padsign` prepends a space to positive values in the output
- `alwayssign` prepends a plus sign to positive values in the output
- `leftalign` places the padding to the right of the value in the output

Floating-point numbers are currently not supported.

For example, the following call converts the hexadecimal number `BAD` to `002989`:

      message($$format_number(BAD, ibase=16 width=6 zeropad))

### fromfile(filename, variablename)

Evaluates `filename` as a qmake project file and returns the value assigned to `variablename`.

See also infile().

### getenv(variablename)

Returns the value of the environment variable `variablename`. This is mostly equivalent to the `$$(variablename)` syntax. The `getenv` function, however, supports environment variables with parentheses in their name.

### join(variablename, glue, before, after)

Joins the value of `variablename` with `glue`. If this value is not empty, this function prefixes the value with `before` and suffixes it with `after`. `variablename` is the only required field, the others default to empty strings. If you need to encode spaces in `glue`, `before`, or `after`, you must quote them.

### last(variablename)

Returns the last value of `variablename`.

For example, the following call returns `phone`:

      CONTACT = firstname middlename surname phone
      message($$last(CONTACT))

See also first().

### list(arg1 [, arg2 ..., argn])

Takes an arbitrary number of arguments. It creates a uniquely named variable that contains a list of the arguments, and returns the name of that variable. You can use the variable to write a loop as illustrated by the following code snippet

      for(var, $$list(foo bar baz)) {
          ...
      }

instead of:

      values = foo bar baz
      for(var, values) {
          ...
      }

### lower(arg1 [, arg2 ..., argn])

Takes an arbitrary number of arguments and converts them to lower case.

See also upper().

### member(variablename, position)

Returns the value at the given `position` in the list of items in `variablename`. If an item cannot be found at the position specified, an empty string is returned. `variablename` is the only required field. If not specified, `position` defaults to 0, causing the first value in the list to be returned.

### prompt(question)

Displays the specified `question`, and returns a value read from stdin.

### quote(string)

Converts a whole `string` into a single entity and returns the result. This is just a fancy way of enclosing the string into double quotes.

### re_escape(string)

Returns the `string` with every special regular expression character escaped with a backslash. This function is a wrapper around QRegExp::escape.

### relative_path(filePath[, base])

Returns the path to `filePath` relative to `base`. If `base` is not specified, it is the current project directory. This function is a wrapper around QDir::relativeFilePath.

See also absolute_path(), clean_path().

### replace(string, old_string, new_string)

Replaces each instance of `old_string` with `new_string` in the contents of the variable supplied as `string`. For example, the code

      MESSAGE = This is a tent.
      message($$replace(MESSAGE, tent, test))

prints the message:

      This is a test.

### sprintf(string, arguments...)

Replaces %1-%9 with the arguments passed in the comma-separated list of function `arguments` and returns the processed string.

### resolve_depends(variablename, prefix)

This is an internal function that you will typically not need.

### reverse(variablename)

Returns the values of `variablename` in reverse order.

### section(variablename, separator, begin, end)

Returns a section of the value of `variablename`. This function is a wrapper around QString::section.

For example, the following call outputs `surname`:

      CONTACT = firstname:middlename:surname:phone
      message($$section(CONTACT, :, 2, 2))

### shadowed(path)

Maps the path from the project source directory to the build directory. This function returns `path` for in-source builds. It returns an empty string if `path` points outside of the source tree.

### shell_path(path)

Converts all directory separators within `path` to separators that are compatible with the shell that is used while building the project (that is, the shell that is invoked by the make tool). For example, slashes are converted to backslashes when the Windows shell is used.

See also system_path().

### shell_quote(arg)

Quotes `arg` for the shell that is used while building the project.

See also system_quote().

### size(variablename)

Returns the number of values of `variablename`.

### sort_depends(variablename, prefix)

This is an internal function that you will typically not need.

### split(variablename, separator)

Splits the value of `variablename` into separate values, and returns them as a list. This function is a wrapper around QString::split.

For example:

      CONTACT = firstname:middlename:surname:phone
      message($$split(CONTACT, :))

### system(command[, mode])

You can use this variant of the `system` function to obtain stdout from the command and assign it to a variable.

For example:

      UNAME = $$system(uname -s)
      contains( UNAME, [lL]inux ):message( This looks like Linux ($$UNAME) to me )

See also the test variant of system().

### system_path(path)

Converts all directory separators within `path` to separators that are compatible with the shell that is used by the `system()` functions to invoke commands. For example, slashes are converted to backslashes for the Windows shell.

See also shell_path().

### system_quote(arg)

Quotes `arg` for the for the shell that is used by the `system()` functions.

See also shell_quote().

### unique(variablename)

Returns the list of values in `variablename` with duplicate entries removed. For example:

      ARGS = 1 2 3 2 5 1
      ARGS = $$unique(ARGS) #1 2 3 5

### upper(arg1 [, arg2 ..., argn])

Takes an arbitrary number of arguments and converts them to upper case.

See also lower().

### val_escape(variablename)

Escapes the values of `variablename` in a way that enables parsing them as qmake code.

Variables ◦ Test Functions