Doc: missing qmake functions

Task-number: QTBUG-28273

Change-Id: Ia3567587d385180b433aa1fe2a50b2c4d99c9401
Reviewed-by: Oswald Buddenhagen <oswald.buddenhagen@digia.com>

2 files changed, 457 insertions, 4 deletions

diff --git a/doc/src/development/qmake-manual.qdoc b/doc/src/development/qmake-manual.qdoc
index 51cf84d1..154c078e 100644
--- a/doc/src/development/qmake-manual.qdoc
+++ b/doc/src/development/qmake-manual.qdoc
@@ -2836,7 +2836,7 @@
     \e {replace functions}. Typically, they return values that you can
     assign to other variables. You can obtain these values by prefixing a
     function with the \c $$ operator. Replace functions can be divided into
-    built-in functions and library functions.
+    built-in functions and function libraries.
 
     See also \l{Test Functions}.
 
@@ -2844,18 +2844,74 @@
 
     Basic replace functions are implemented as built-in functions.
 
+    \section2 absolute_path(path[, base])
+
+    Returns the absolute path of \c path.
+
+    If \c base is not specified, uses the current directory as the base
+    directory.
+
+    For example, the following call returns the string
+    \c {"/home/johndoe/myproject/readme.txt"}:
+
+    \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 159
+
+    See also \l{clean_path(path)}{clean_path()},
+    \l{relative_path(filePath[, base])}{relative_path()}.
+
     \section2 basename(variablename)
 
     Returns the basename of the file specified. For example:
 
     \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 59
 
+    \section2 cat(filename[, mode])
+
+    Returns the contents of \c filename. You can specify the following options
+    for \c mode:
+
+    \list
+        \li \c blob returns the entire contents of the file as one value
+        \li \c lines returns each line as a separate value (without line
+            endings)
+        \li \c true (default value) and \c false return file contents as
+            separate values, split according to qmake value list splitting rules
+            (as in variable assignments). If \c mode is \c false, values that
+            contain only a newline character are inserted into the list to
+            indicate where line breaks were in the file.
+    \endlist
+
+    \section2 clean_path(path)
+
+    Returns \c 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 \l{absolute_path(path[, base])}{absolute_path()},
+    \l{relative_path(filePath[, base])}{relative_path()},
+    \l{shell_path(path)}{shell_path()}, \l{system_path(path)}{system_path()}.
+
     \section2 dirname(file)
 
     Returns the directory name part of the specified file. For example:
 
     \snippet doc/src/snippets/qmake/dirname.pro 0
 
+    \section2 enumerate_vars
+
+    Returns a list of all defined variable names.
+
+    \section2 escape_expand(arg1 [, arg2 ..., argn])
+
+    This function accepts an arbitrary number of arguments. It expands the
+    escape sequences \c {\n}, \c {\r}, \c {\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:
+
+    \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 173
+
     \section2 find(variablename, substr)
 
     Places all the values in \e variablename that match \e substr. \e
@@ -2866,6 +2922,47 @@
     MY_VAR2 will contain '-Lone -Ltwo -Lthree -Lfour -Lfive', and MY_VAR3 will
     contains 'three two three'.
 
+    \section2 first(variablename)
+
+    Returns the first value of \c variablename.
+
+    For example, the following call returns \c firstname:
+
+    \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 161
+
+    See also \l{last(variablename)}{last()}.
+
+    \section2 format_number(number[, options...])
+
+    Returns \c number in the format specified by \c options. You can specify the
+    following options:
+
+    \list
+        \li \c ibase=n sets the base of the input to \c n
+        \li \c obase=n sets the base of the output to \c n
+        \li \c width=n sets the minimum width of the output to \c n. If the
+            output is shorter than \c width, it is padded with spaces
+        \li \c zeropad pads the output with zeroes instead of spaces
+        \li \c padsign prepends a space to positive values in the output
+        \li \c alwayssign prepends a plus sign to positive values in the output
+        \li \c leftalign places the padding to the right of the value in the
+            output
+    \endlist
+
+    Floating-point numbers are currently not supported.
+
+    For example, the following call converts the hexadecimal number \c BAD to
+    \c 002989:
+
+    \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 163
+
+    \section2 fromfile(filename, variablename)
+
+    Evaluates \c filename as a qmake project file and returns the value assigned
+    to \c variablename.
+
+    See also \l{infile(filename, var, val)}{infile()}.
+
     \section2 join(variablename, glue, before, after)
 
     Joins the value of \e variablename with \c glue. If this value is
@@ -2874,6 +2971,35 @@
     to empty strings. If you need to encode spaces in \e glue, \e before, or \e
     after you must quote them.
 
+    \section2 last(variablename)
+
+    Returns the last value of \c variablename.
+
+    For example, the following call returns \c phone:
+
+    \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 162
+
+    See also \l{first(variablename)}{first()}.
+
+    \section2 list(arg1 [, arg2 ..., argn])
+
+    This function 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
+
+    \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 170
+
+    instead of:
+
+    \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 171
+
+    \section2 lower(arg1 [, arg2 ..., argn])
+
+    Takes an arbitrary number of arguments and converts them to lower case.
+
+    See also \l{upper(arg1 [, arg2 ..., argn])}{upper()}.
+
     \section2 member(variablename, position)
 
     Returns the value at the given \e position in the list of items in
@@ -2892,6 +3018,20 @@
     Converts a whole \e string into a single entity and returns the result.
     This is just a fancy way of enclosing the string into double quotes.
 
+    \section2 re_escape(string)
+
+    Returns the \c string with every special regular expression character
+    escaped with a backslash. This function is a wrapper around QRegExp::escape.
+
+    \section2 relative_path(filePath[, base])
+
+    Returns the path to \c filePath relative to \c base. If \c base is not
+    specified, it is the current project directory. This function is a wrapper
+    around QDir::relativeFilePath.
+
+    See also \l{absolute_path(path[, base])}{absolute_path()},
+    \l{clean_path(path)}{clean_path()}.
+
     \section2 replace(string, old_string, new_string)
 
     Replaces each instance of \c old_string with \c new_string in the
@@ -2909,6 +3049,61 @@
     Replaces %1-%9 with the arguments passed in the comma-separated list
     of function \e arguments and returns the processed string.
 
+    \section2 resolve_depends(variablename, prefix)
+
+    This is an internal function that you will typically not need.
+
+    \section2 reverse(variablename)
+
+    Returns the values of \c variablename in reverse order.
+
+    \section2 section(variablename, separator, begin, end)
+
+    Returns a section of the value of \c variablename. This function is a
+    wrapper around QString::section.
+
+    For example, the following call outputs \c surname:
+
+    \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 167
+
+    \section2 shadowed(path)
+
+    Maps the path from the project source directory to the build directory.
+    This function returns \c path for in-source builds. It returns an empty
+    string if \c path points outside of the source tree.
+
+    \section2 shell_path(path)
+
+    Converts all directory separators within \c 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 \l{system_path(path)}{system_path()}.
+
+    \section2 shell_quote(arg)
+
+    Quotes \c arg for the shell that is used while building the project.
+
+    See also \l{system_quote(arg)}{system_quote()}.
+
+    \section2 size(variablename)
+
+    Returns the number of values of \c variablename.
+
+    \section2 sort_depends(variablename, prefix)
+
+    This is an internal function that you will typically not need.
+
+    \section2 split(variablename, separator)
+
+    Splits the value of \c variablename into separate values, and returns them
+    as a list. This function is a wrapper around QString::split.
+
+    For example:
+
+    \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 168
+
     \section2 system(command[, mode])
 
     You can use this variant of the \c system function to obtain stdout from the
@@ -2918,7 +3113,23 @@
 
     \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 72
 
-    See also \l{system(command)}.
+    See also the test variant of \l{system(command)}{system()}.
+
+    \section2 system_path(path)
+
+    Converts all directory separators within \c path to separators that are
+    compatible with the shell that is used by the \c{system()} functions to
+    invoke commands. For example, slashes are converted to backslashes for the
+    Windows shell.
+
+    See also \l{shell_path(path)}{shell_path()}.
+
+    \section2 system_quote(arg)
+
+    Quotes \c arg for the for the shell that is used by the \c{system()}
+    functions.
+
+    See also \l{shell_quote(arg)}{shell_quote()}.
 
     \target unique
     \section2 unique(variablename)
@@ -2927,6 +3138,17 @@
     with repetitive entries removed). For example:
 
     \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 73
+
+    \section2 upper(arg1 [, arg2 ..., argn])
+
+    Takes an arbitrary number of arguments and converts them to upper case.
+
+    See also \l{lower(arg1 [, arg2 ..., argn])}{lower()}.
+
+    \section2 val_escape(variablename)
+
+    Escapes the values of \c variablename in a way that enables parsing them as
+    qmake code.
 */
 
 /*!
@@ -2937,7 +3159,7 @@
 
     Test functions return a boolean value that you can test for in the
     conditional parts of scopes. Test functions can be divided into
-    built-in functions and library functions.
+    built-in functions and function libraries.
 
     See also \l{Replace Functions}.
 
@@ -2945,6 +3167,10 @@
 
     Basic test functions are implemented as built-in functions.
 
+    \section2 cache(variablename, [set|add|sub] [transient] [super], [source variablename])
+
+    This is an internal function that you will typically not need.
+
     \section2 CONFIG(config)
 
     This function can be used to test for variables placed into the
@@ -2988,6 +3214,31 @@
 
     \snippet doc/src/snippets/qmake/functions.pro 2
 
+    \section2 debug(level, message)
+
+    Checks whether qmake runs at the specified debug level. If yes, it returns
+    true and prints a debug message.
+
+    \section2 defined(name[, type])
+
+    Tests whether the function or variable \c name is defined. If \c type is
+    omitted, checks all functions. To check only variables or particular type of
+    functions, specify \c type. It can have the following values:
+
+    \list
+        \li \c test only checks test functions
+        \li \c replace only checks replace functions
+        \li \c var only checks variables
+    \endlist
+
+    \section2 equals(variablename, value)
+
+    Tests whether \c variablename equals the string \c value.
+
+    For example:
+
+    \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 160
+
     \section2 error(string)
 
     This function never returns a value. \l{qmake Manual#qmake}{\c qmake}
@@ -3024,6 +3275,16 @@
     Note that "/" can be used as a directory separator, regardless of the
     platform in use.
 
+    \section2 export(variablename)
+
+    Exports the current value of \c variablename from the local context of a
+    function to the global context.
+
+    \section2 files(pattern[, recursive=false])
+
+    Expands the specified wildcard pattern and returns a list of filenames.
+    If \c recursive is true, this function descends into subdirectories.
+
     \section2 for(iterate, list)
 
     This special test function will cause a loop to be started that
@@ -3038,6 +3299,35 @@
 
     \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 65
 
+    \section2 greaterThan(variablename, value)
+
+    Tests that the value of \c variablename is greater than \c value. First,
+    this function attempts a numerical comparison. If at least one of the
+    operands fails to convert, this function does a string comparison.
+
+    For example:
+
+    \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 164
+
+    It is impossible to compare two numbers as strings directly. As a
+    workaround, construct temporary values with a non-numeric prefix and compare
+    these.
+
+    For example:
+
+    \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 172
+
+    See also \l{lessThan(variablename, value)}{lessThan()}.
+
+    \section2 if(condition)
+
+    This test function evaluates \c condition. It is used to group boolean
+    expressions.
+
+    For example:
+
+    \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 166
+
     \section2 include(filename)
 
     Includes the contents of the file specified by \e filename into the
@@ -3058,6 +3348,10 @@
     (\e val), the function will only test whether \e var has been declared in
     the file.
 
+    \section2 isActiveConfig
+
+    This is an alias for the \c CONFIG function.
+
     \section2 isEmpty(variablename)
 
     Succeeds if the variable \e variablename is empty; otherwise fails.
@@ -3067,6 +3361,31 @@
 
     \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 67
 
+    \section2 isEqual
+
+    This is an alias for the \c equals function.
+
+    \section2 lessThan(variablename, value)
+
+    Tests that the value of \c variablename is less than \c value. Works as
+    \l{greaterThan(variablename, value)}{greaterThan()}.
+
+    For example:
+
+    \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 165
+
+    \section2 load(feature)
+
+    This function loads the feature file (\c .prf) specified by \c feature,
+    unless the feature has already been loaded.
+
+    \section2 log(message)
+
+    Prints a message on the console. Unlike the \c message function, neither
+    prepends text nor appends a line break.
+
+    See also \l{message(string)}{message()}.
+
     \section2 message(string)
 
     This function simply writes a message to the console. Unlike the
@@ -3085,6 +3404,21 @@
 
     \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 69
 
+    \section2 mkpath(dirPath)
+
+    Creates the directory path \c dirPath. This function is a wrapper around the
+    QDir::makepath function.
+
+    \section2 requires(condition)
+
+    Evaluates \c condition. If the condition is false, qmake skips this
+    project (and its SUBDIRS) when building.
+
+    \note You can also use the REQUIRES variable for this purpose. However, we
+    recommend using this function, instead.
+
+    See also \l{REQUIRES}.
+
     \section2 system(command)
 
     Executes the given \c command in a secondary shell. Succeeds
@@ -3095,13 +3429,33 @@
 
     \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 71
 
-    See also \l{system(command[, mode])}.
+    See also the replace variant of \l{system(command[, mode])}{system()}.
+
+    \section2 touch(filename, reference_filename)
+
+    Updates the time stamp of \c filename to match the time stamp of
+    \c reference_filename.
+
+    \section2 unset(variablename)
+
+    Removes \c variablename from the current context.
+
+    For example:
+
+    \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 169
 
     \section2 warning(string)
 
     This function will always succeed, and will display the given
     \c string to the user. message() is a synonym for warning().
 
+    \section2 write_file(filename, [variablename, [mode]])
+
+    Writes the values of \c variablename to a file with the name \c filename,
+    each value on a separate line. If \c variablename is not specified, creates
+    an empty file. If \c mode is \c append and the file already exists, appends
+    to it instead of replacing it.
+
     \section1 Test Function Library
 
     Complex test functions are implemented in a library of .prf files.
diff --git a/doc/src/snippets/code/doc_src_qmake-manual.pro b/doc/src/snippets/code/doc_src_qmake-manual.pro
index b75d4de4..0f95d767 100644
--- a/doc/src/snippets/code/doc_src_qmake-manual.pro
+++ b/doc/src/snippets/code/doc_src_qmake-manual.pro
@@ -845,3 +845,102 @@ packagesExist(sqlite3 QtNetwork QtDeclarative) {
     // Use the fancy UI, as we have extra packages available
 #endif
 #! [158]
+
+#! [159]
+message($$absolute_path("readme.txt", "/home/johndoe/myproject"))
+#! [159]
+
+
+#! [160]
+TARGET = helloworld
+equals(TARGET, "helloworld") {
+    message("The target assignment was successful.")
+}
+#! [160]
+
+
+#! [161]
+CONTACT = firstname middlename surname phone
+message($$first(CONTACT))
+#! [161]
+
+
+#! [162]
+CONTACT = firstname middlename surname phone
+message($$last(CONTACT))
+#! [162]
+
+
+#! [163]
+message($$format_number(BAD, ibase=16 width=6 zeropad))
+#! [163]
+
+
+#! [164]
+ANSWER = 42
+greaterThan(ANSWER, 1) {
+    message("The answer might be correct.")
+}
+#! [164]
+
+
+#! [165]
+ANSWER = 42
+lessThan(ANSWER, 1) {
+    message("The answer might be wrong.")
+}
+#! [165]
+
+
+#! [166]
+if(linux-g++*|macx-g++*):CONFIG(debug, debug|release) {
+    message("We are on Linux or Mac OS, and we are in debug mode.")
+}
+#! [166]
+
+
+#! [167]
+CONTACT = firstname:middlename:surname:phone
+message($$section(CONTACT, :, 2, 2))
+#! [167]
+
+
+#! [168]
+CONTACT = firstname:middlename:surname:phone
+message($$split(CONTACT, :))
+#! [168]
+
+#! [169]
+NARF = zort
+unset(NARF)
+!defined(NARF, var) {
+    message("NARF is not defined.")
+}
+#! [169]
+
+
+#! [170]
+for(var, $$list(foo bar baz)) {
+    ...
+}
+#! [170]
+
+
+#! [171]
+values = foo bar baz
+for(var, values) {
+    ...
+}
+#! [171]
+
+
+#! [172]
+VALUE = 123
+TMP_VALUE = x$$VALUE
+greaterThan(TMP_VALUE, x456): message("Condition may be true.")
+#! [172]
+
+
+#! [173]
+message("First line$$escape_expand(\\n)Second line")
+#! [173]