Lenguaje qmake

Muchos archivos de proyecto qmake simplemente describen las fuentes y archivos de cabecera utilizados por el proyecto, utilizando una lista de name = value y name += value definiciones. qmake también proporciona otros operadores, funciones y ámbitos que se pueden utilizar para procesar la información proporcionada en las declaraciones de variables. Estas funciones avanzadas permiten generar Makefiles para múltiples plataformas a partir de un único archivo de proyecto.

Operadores

En muchos archivos de proyecto, los operadores assignment (=) y append (+=) pueden utilizarse para incluir toda la información sobre un proyecto. El patrón típico de uso es asignar una lista de valores a una variable, y añadir más valores dependiendo del resultado de varias pruebas. Dado que qmake define ciertas variables utilizando valores por defecto, a veces es necesario utilizar el operador de eliminación (-=) para filtrar los valores que no son necesarios. Las siguientes secciones describen cómo utilizar los operadores para manipular el contenido de las variables.

Asignación de valores

El operador = asigna un valor a una variable:

TARGET = myapp

La línea anterior establece la variable TARGET en myapp. Esto sobrescribirá cualquier valor establecido previamente para TARGET con myapp.

Añadir valores

El operador += añade un nuevo valor a la lista de valores de una variable:

DEFINES += USE_MY_STUFF

La línea anterior añade USE_MY_STUFF a la lista de definiciones del preprocesador que se incluirán en el Makefile generado.

Eliminación de valores

El operador -= elimina un valor de la lista de valores de una variable:

DEFINES -= USE_MY_STUFF

La línea anterior elimina USE_MY_STUFF de la lista de definiciones de preprocesador que se incluirán en el Makefile generado.

Añadir valores únicos

El operador *= añade un valor a la lista de valores de una variable, pero sólo si no está ya presente. Esto evita que los valores se incluyan muchas veces en una variable. Por ejemplo:

DEFINES *= USE_MY_STUFF

En la línea anterior, USE_MY_STUFF sólo se añadirá a la lista de definiciones del preprocesador si no está ya definida. Tenga en cuenta que la función unique() también puede utilizarse para garantizar que una variable sólo contiene una instancia de cada valor.

Sustitución de valores

El operador ~= sustituye cualquier valor que coincida con una expresión regular por el valor especificado:

DEFINES ~= s/QT_[DT].+/QT

En la línea anterior, cualquier valor de la lista que empiece por QT_D o QT_T se sustituye por QT.

Expansión de variables

El operador $$ se utiliza para extraer el contenido de una variable, y puede utilizarse para pasar valores entre variables o suministrarlos a funciones:

EVERYTHING = $$SOURCES $$HEADERS
message("The project contains the following files:")
message($$EVERYTHING)

Las variables pueden utilizarse para almacenar el contenido de variables de entorno. Éstas pueden ser evaluadas en el momento en que se ejecuta qmake, o incluidas en el Makefile generado para su evaluación cuando se construye el proyecto.

Para obtener el contenido de un valor de entorno cuando qmake se ejecuta, utilice el operador $$(...):

DESTDIR = $$(PWD)
message(The project will be installed in $$DESTDIR)

En la asignación anterior, el valor de la variable de entorno PWD se lee cuando se procesa el archivo de proyecto.

Para obtener el contenido de un valor de entorno en el momento en que se procesa el Makefile generado, utilice el operador $(...):

DESTDIR = $$(PWD)
message(The project will be installed in $$DESTDIR)

DESTDIR = $(PWD)
message(The project will be installed in the value of PWD)
message(when the Makefile is processed.)

En la asignación anterior, el valor de PWD se lee inmediatamente cuando se procesa el fichero de proyecto, pero $(PWD) se asigna a DESTDIR en el Makefile generado. Esto hace que el proceso de compilación sea más flexible siempre y cuando la variable de entorno se establezca correctamente cuando se procese el Makefile.

Acceso a las propiedades de qmake

El operador especial $$[...] puede utilizarse para acceder a las propiedades de qmake:

message(Qt version: $$[QT_VERSION])
message(Qt is installed in $$[QT_INSTALL_PREFIX])
message(Qt resources can be found in the following locations:)
message(Documentation: $$[QT_INSTALL_DOCS])
message(Header files: $$[QT_INSTALL_HEADERS])
message(Libraries: $$[QT_INSTALL_LIBS])
message(Binary files (executables): $$[QT_INSTALL_BINS])
message(Plugins: $$[QT_INSTALL_PLUGINS])
message(Data files: $$[QT_INSTALL_DATA])
message(Translation files: $$[QT_INSTALL_TRANSLATIONS])
message(Settings: $$[QT_INSTALL_CONFIGURATION])
message(Examples: $$[QT_INSTALL_EXAMPLES])

Para obtener más información, consulte Configuración de qmake.

Las propiedades accesibles con este operador se utilizan normalmente para permitir que plugins y componentes de terceros se integren en Qt. Por ejemplo, un plugin de Qt Widgets Designer puede instalarse junto con los plugins incorporados de Qt Widgets Designer si se realiza la siguiente declaración en su archivo de proyecto:

target.path = $$[QT_INSTALL_PLUGINS]/designer
INSTALLS += target

Ámbitos

Los ámbitos son similares a las declaraciones if en los lenguajes de programación procedimentales. Si cierta condición es verdadera, las declaraciones dentro del ámbito son procesadas.

Sintaxis de los ámbitos

Los ámbitos constan de una condición seguida de una llave de apertura en la misma línea, una secuencia de comandos y definiciones, y una llave de cierre en una nueva línea:

<condition> {
    <command or definition>
    ...
}

La llave de apertura debe escribirse en la misma línea que la condición. Los ámbitos pueden concatenarse para incluir más de una condición, como se describe en las secciones siguientes.

Ámbitos y condiciones

Un ámbito se escribe como una condición seguida de una serie de declaraciones contenidas dentro de un par de llaves. Por ejemplo:

win32 {
    SOURCES += paintwidget_win.cpp
}

El código anterior añadirá el archivo paintwidget_win.cpp a los fuentes listados en el Makefile generado cuando se construya para una plataforma Windows. Cuando se construya para otras plataformas, la definición será ignorada.

Las condiciones utilizadas en un ámbito determinado también se pueden negar para proporcionar un conjunto alternativo de declaraciones que se procesarán sólo si la condición original es falsa. Por ejemplo, para procesar algo cuando se construye para todas las plataformas excepto Windows, niegue el ámbito así:

!win32 {
    SOURCES -= paintwidget_win.cpp
}

Los ámbitos pueden anidarse para combinar más de una condición. Por ejemplo, para incluir un archivo en particular para una determinada plataforma sólo si la depuración está activada, escriba lo siguiente:

macx {
    CONFIG(debug, debug|release) {
        HEADERS += debugging.h
    }
}

Para ahorrar la escritura de muchos ámbitos anidados, puede anidar ámbitos utilizando el operador :. Los ámbitos anidados del ejemplo anterior pueden reescribirse de la siguiente manera:

macx:CONFIG(debug, debug|release) {
    HEADERS += debugging.h
}

También puede utilizar el operador : para realizar asignaciones condicionales de una sola línea. Por ejemplo:

win32:DEFINES += USE_MY_STUFF

La línea anterior añade USE_MY_STUFF a la variable DEFINES sólo cuando se construye para la plataforma Windows. Generalmente, el operador : se comporta como un operador lógico AND, uniendo un número de condiciones, y requiriendo que todas ellas sean verdaderas.

También existe el operador | para actuar como un operador lógico OR, uniendo varias condiciones y requiriendo que sólo una de ellas sea verdadera.

win32|macx {
    HEADERS += debugging.h
}

Si necesita mezclar ambos operadores, puede utilizar la función if para especificar la precedencia del operador.

if(win32|macos):CONFIG(debug, debug|release) {
    # Do something on Windows and macOS,
    # but only for the debug configuration.
}
win32|if(macos:CONFIG(debug, debug|release)) {
    # Do something on Windows (regardless of debug or release)
    # and on macOS (only for debug).
}

La condición acepta el carácter comodín para coincidir con una familia de valores CONFIG o nombres mkspec.

win32-* {
    # Matches every mkspec starting with "win32-"
    SOURCES += win32_specific.cpp
}

También puede proporcionar declaraciones alternativas a las de un ámbito utilizando un ámbito else. Cada ámbito else se procesa si las condiciones de los ámbitos precedentes son falsas. Esto permite escribir pruebas complejas cuando se combinan con otros ámbitos (separados por el operador : como se ha indicado anteriormente). Por ejemplo

win32:xml {
    message(Building for Windows)
    SOURCES += xmlhandler_win.cpp
} else:xml {
    SOURCES += xmlhandler.cpp
} else {
    message("Unknown configuration")
}

Configuración y ámbitos

Los valores almacenados en la variable CONFIG reciben un tratamiento especial por parte de qmake. Cada uno de los valores posibles puede utilizarse como condición para un ámbito. Por ejemplo, la lista de valores que contiene CONFIG puede ampliarse con el valor opengl:

CONFIG += opengl

Como resultado de esta operación, cualquier ámbito que compruebe opengl será procesado. Podemos utilizar esta función para dar al ejecutable final un nombre apropiado:

opengl {
    TARGET = application-gl
} else {
    TARGET = application
}

Esta característica hace que sea fácil cambiar la configuración de un proyecto sin perder todos los ajustes personalizados que puedan ser necesarios para una configuración específica. En el código anterior, las declaraciones en el primer ámbito se procesan, y el ejecutable final se llamará application-gl. Sin embargo, si no se especifica opengl, se procesarán las declaraciones del segundo ámbito y el ejecutable final se llamará application.

Dado que es posible poner sus propios valores en la línea CONFIG, esto le proporciona una forma conveniente de personalizar los archivos de proyecto y ajustar los Makefiles generados.

Valores de alcance de la plataforma

Además de los valores win32, macx, y unix utilizados en muchas condiciones de ámbito, se pueden probar con ámbitos otros valores específicos de la plataforma y del compilador. Éstos se basan en las especificaciones de plataforma proporcionadas en el directorio mkspecs de Qt. Por ejemplo, las siguientes líneas de un archivo de proyecto muestran la especificación actual en uso y comprueban la especificación linux-g++:

message($$QMAKESPEC)

linux-g++ {
    message(Linux)
}

Puedes probar cualquier otra combinación plataforma-compilador siempre que exista una especificación para ella en el directorio mkspecs.

Variables

Muchas de las variables utilizadas en los archivos de proyecto son variables especiales que qmake utiliza al generar Makefiles, como DEFINES, SOURCES y HEADERS. Además, puede crear variables para su propio uso. qmake crea nuevas variables con un nombre determinado cuando encuentra una asignación a ese nombre. Por ejemplo:

MY_VARIABLE = value

No hay restricciones en lo que haces a tus propias variables, como qmake las ignorará a menos que necesite evaluarlas al procesar un ámbito.

También puede asignar el valor de una variable actual a otra variable anteponiendo $$ al nombre de la variable. Por ejemplo:

MY_DEFINES = $$DEFINES

Ahora la variable MY_DEFINES contiene lo que hay en la variable DEFINES en este punto del archivo de proyecto. Esto también es equivalente a:

MY_DEFINES = $${DEFINES}

La segunda notación le permite añadir el contenido de la variable a otro valor sin separar los dos con un espacio. Por ejemplo, lo siguiente garantizará que el ejecutable final tenga un nombre que incluya la plantilla de proyecto que se está utilizando:

TARGET = myproject_$${TEMPLATE}

Reemplazar funciones

qmake proporciona una selección de funciones integradas que permiten procesar el contenido de las variables. Estas funciones procesan los argumentos que se les suministran y devuelven un valor, o una lista de valores, como resultado. Para asignar un resultado a una variable, utilice el operador $$ con este tipo de función como lo haría para asignar el contenido de una variable a otra:

HEADERS = model.h
HEADERS += $$OTHER_HEADERS
HEADERS = $$unique(HEADERS)

Este tipo de función debe utilizarse en el lado derecho de las asignaciones (es decir, como operando).

Puede definir sus propias funciones para procesar el contenido de las variables del siguiente modo:

defineReplace(functionName){
    #function code
}

La siguiente función de ejemplo toma un nombre de variable como único argumento, extrae una lista de valores de la variable con la función incorporada eval() y compila una lista de ficheros:

defineReplace(headersAndSources) {
    variable = $$1
    names = $$eval($$variable)
    headers =
    sources =

    for(name, names) {
        header = $${name}.h
        exists($$header) {
            headers += $$header
        }
        source = $${name}.cpp
        exists($$source) {
            sources += $$source
        }
    }
    return($$headers $$sources)
}

Funciones de prueba

qmake proporciona funciones integradas que se pueden utilizar como condiciones al escribir ámbitos. Estas funciones no devuelven un valor, sino que indican éxito o fracaso:

count(options, 2) {
    message(Both release and debug specified.)
}

Este tipo de función sólo debe utilizarse en expresiones condicionales.

Es posible definir sus propias funciones para proporcionar condiciones a los ámbitos. El siguiente ejemplo comprueba si existe cada archivo de una lista y devuelve verdadero si existen todos, o falso en caso contrario:

defineTest(allFiles) {
    files = $$ARGS

    for(file, files) {
        !exists($$file) {
            return(false)
        }
    }
    return(true)
}