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.