Langage qmake

De nombreux fichiers de projet qmake se contentent de décrire les fichiers sources et les fichiers d'en-tête utilisés par le projet, à l’aide d’une liste de définitions de type name = value et name += value. qmake fournit également d’autres opérateurs, fonctions et portées pouvant être utilisés pour traiter les informations fournies dans les déclarations de variables. Ces fonctionnalités avancées permettent de générer des Makefiles pour plusieurs plateformes à partir d’un seul fichier de projet.

Opérateurs

Dans de nombreux fichiers de projet, les opérateurs d’affectation (=) et d’ajout (+=) peuvent être utilisés pour inclure toutes les informations relatives à un projet. Le schéma d’utilisation classique consiste à attribuer une liste de valeurs à une variable, puis à y ajouter d’autres valeurs en fonction du résultat de divers tests. Étant donné que qmake définit certaines variables avec des valeurs par défaut, il est parfois nécessaire d’utiliser l’opérateur de suppression (-=) pour filtrer les valeurs qui ne sont pas requises. Les sections suivantes décrivent comment utiliser les opérateurs pour manipuler le contenu des variables.

Affectation de valeurs

L’opérateur « = » attribue une valeur à une variable :

TARGET = myapp

La ligne ci-dessus définit la variable TARGET sur myapp. Cela écrasera toute valeur précédemment définie pour TARGET par myapp.

Ajout de valeurs

L'opérateur « += » ajoute une nouvelle valeur à la liste des valeurs d'une variable :

DEFINES += USE_MY_STUFF

La ligne ci-dessus ajoute USE_MY_STUFF à la liste des définitions du préprocesseur à inclure dans le Makefile généré.

Suppression de valeurs

L'opérateur -= supprime une valeur de la liste des valeurs d'une variable :

DEFINES -= USE_MY_STUFF

La ligne ci-dessus supprime « USE_MY_STUFF » de la liste des définitions du préprocesseur à inclure dans le Makefile généré.

Ajout de valeurs uniques

L’opérateur ` *= ` ajoute une valeur à la liste des valeurs d’une variable, mais uniquement si celle-ci n’y figure pas déjà. Cela empêche qu’une même valeur soit incluse plusieurs fois dans une variable. Par exemple :

DEFINES *= USE_MY_STUFF

Dans la ligne ci-dessus, USE_MY_STUFF ne sera ajouté à la liste des définitions du préprocesseur que s’il n’est pas déjà défini. Notez que la fonction unique() peut également être utilisée pour s’assurer qu’une variable ne contient qu’une seule instance de chaque valeur.

Remplacement de valeurs

L’opérateur ~= remplace toutes les valeurs correspondant à une expression régulière par la valeur spécifiée :

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

Dans la ligne ci-dessus, toutes les valeurs de la liste commençant par « QT_D » ou « QT_T » sont remplacées par « QT ».

Expansion de variables

L'opérateur $$ sert à extraire le contenu d'une variable et peut être utilisé pour transmettre des valeurs entre variables ou les fournir à des fonctions :

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

Les variables peuvent servir à stocker le contenu de variables d’environnement. Celles-ci peuvent être évaluées au moment de l’exécution de qmake, ou incluses dans le Makefile généré pour être évaluées lors de la compilation du projet.

Pour obtenir le contenu d’une valeur d’environnement lors de l’exécution de qmake, utilisez l’opérateur « $$(...) » :

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

Dans l'affectation ci-dessus, la valeur de la variable d'environnement ` PWD ` est lue lors du traitement du fichier de projet.

Pour obtenir la valeur d’une variable d’environnement au moment du traitement du Makefile généré, utilisez l’opérateur ` $(...) ` :

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.)

Dans l’affectation ci-dessus, la valeur de PWD est lue immédiatement lors du traitement du fichier de projet, mais $(PWD) est affectée à DESTDIR dans le Makefile généré. Cela rend le processus de compilation plus flexible, à condition que la variable d’environnement soit correctement définie au moment du traitement du Makefile.

Accès aux propriétés de qmake

L'opérateur spécial $$[...] permet d'accéder aux propriétés 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])

Pour plus d’informations, consultez la section Configuration de qmake.

Les propriétés accessibles via cet opérateur sont généralement utilisées pour permettre l’intégration de plugins et de composants tiers dans Qt. Par exemple, un plugin Designer d’ Qt Widgets peut être installé aux côtés des plugins intégrés d’ Qt Widgets Qt Designer si la déclaration suivante est effectuée dans son fichier de projet :

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

Portées

Les portées sont similaires aux instructions « if » des langages de programmation procéduraux. Si une certaine condition est vraie, les déclarations situées à l'intérieur de la portée sont traitées.

Syntaxe des portées

Les portées se composent d’une condition suivie d’une accolade ouvrante sur la même ligne, d’une séquence de commandes et de définitions, puis d’une accolade fermante sur une nouvelle ligne :

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

L'accolade ouvrante doit être écrite sur la même ligne que la condition. Les portées peuvent être concaténées pour inclure plusieurs conditions, comme décrit dans les sections suivantes.

Portées et conditions

Une portée s’écrit sous la forme d’une condition suivie d’une série de déclarations contenues entre une paire d’accolades. Par exemple :

win32 {
    SOURCES += paintwidget_win.cpp
}

Le code ci-dessus ajoutera le fichier paintwidget_win.cpp aux sources répertoriées dans le Makefile généré lors de la compilation pour une plate-forme Windows. Lors de la compilation pour d'autres plates-formes, cette définition sera ignorée.

Les conditions utilisées dans une portée donnée peuvent également être inversées afin de fournir un ensemble alternatif de déclarations qui ne seront traitées que si la condition d’origine est fausse. Par exemple, pour traiter quelque chose lors de la compilation pour toutes les plateformes sauf Windows, inversez la portée comme suit :

!win32 {
    SOURCES -= paintwidget_win.cpp
}

Les portées peuvent être imbriquées pour combiner plusieurs conditions. Par exemple, pour inclure un fichier particulier pour une certaine plateforme uniquement si le débogage est activé, écrivez ce qui suit :

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

Pour éviter d’écrire de nombreuses portées imbriquées, vous pouvez imbriquer les portées à l’aide de l’opérateur ` : `. Les portées imbriquées de l’exemple ci-dessus peuvent être réécrites de la manière suivante :

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

Vous pouvez également utiliser l’opérateur ` : ` pour effectuer des affectations conditionnelles sur une seule ligne. Par exemple :

win32:DEFINES += USE_MY_STUFF

La ligne ci-dessus ajoute « USE_MY_STUFF » à la variable DEFINES uniquement lors de la compilation pour la plate-forme Windows. En général, l’opérateur « : » se comporte comme un opérateur logique ET, en combinant plusieurs conditions et en exigeant qu’elles soient toutes vraies.

Il existe également l’opérateur « | », qui agit comme un opérateur logique OR : il combine plusieurs conditions et exige qu’une seule d’entre elles soit vraie.

win32|macx {
    HEADERS += debugging.h
}

Si vous devez combiner ces deux opérateurs, vous pouvez utiliser la fonction ` if ` pour spécifier la priorité des opérateurs.

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 condition accepte le caractère générique pour correspondre à une famille de valeurs « CONFIG » ou de noms « mkspec ».

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

Vous pouvez également fournir des déclarations alternatives à celles d’une portée donnée en utilisant une portée « else ». Chaque portée « else » est traitée si les conditions des portées précédentes sont fausses. Cela vous permet d’écrire des tests complexes lorsqu’elles sont combinées avec d’autres portées (séparées par l’opérateur « : » comme ci-dessus). Par exemple :

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

Configuration et portées

Les valeurs stockées dans la variable CONFIG font l’objet d’un traitement particulier par qmake. Chacune des valeurs possibles peut être utilisée comme condition pour une portée. Par exemple, la liste des valeurs contenues dans CONFIG peut être étendue avec la valeur opengl:

CONFIG += opengl

À la suite de cette opération, toutes les portées vérifiant la présence de « opengl » seront traitées. Nous pouvons utiliser cette fonctionnalité pour attribuer un nom approprié à l’exécutable final :

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

Cette fonctionnalité facilite la modification de la configuration d’un projet sans perdre tous les paramètres personnalisés qui pourraient être nécessaires pour une configuration spécifique. Dans le code ci-dessus, les déclarations de la première portée sont traitées, et l’exécutable final s’appellera application-gl. Toutefois, si opengl n’est pas spécifié, ce sont les déclarations de la deuxième portée qui sont traitées à la place, et l’exécutable final s’appellera application.

Comme il est possible d’indiquer vos propres valeurs sur la ligne « CONFIG », cela vous offre un moyen pratique de personnaliser les fichiers de projet et d’affiner les Makefiles générés.

Valeurs de la portée « platform »

Outre les valeurs win32, macx et unix utilisées dans de nombreuses conditions de portée, diverses autres valeurs intégrées spécifiques à la plate-forme et au compilateur peuvent être testées avec les portées. Celles-ci s’appuient sur les spécifications de plate-forme fournies dans le répertoire mkspecs de Qt. Par exemple, les lignes suivantes, issues d’un fichier de projet, indiquent la spécification actuellement utilisée et testent la spécification linux-g++:

message($$QMAKESPEC)

linux-g++ {
    message(Linux)
}

Vous pouvez tester n'importe quelle autre combinaison plateforme-compilateur, à condition qu'une spécification existe pour celle-ci dans le répertoire mkspecs.

Variables

Bon nombre des variables utilisées dans les fichiers de projet sont des variables spéciales que qmake utilise lors de la génération des Makefiles, telles que DEFINES, SOURCES et HEADERS. De plus, vous pouvez créer des variables pour votre usage personnel. qmake crée de nouvelles variables portant un nom donné lorsqu’il rencontre une affectation à ce nom. Par exemple :

MY_VARIABLE = value

Il n’y a aucune restriction quant à ce que vous pouvez faire avec vos propres variables, car qmake les ignorera à moins qu’il n’ait besoin de les évaluer lors du traitement d’une portée.

Vous pouvez également attribuer la valeur d’une variable actuelle à une autre variable en préfixant le nom de la variable par $$. Par exemple :

MY_DEFINES = $$DEFINES

Désormais, la variable MY_DEFINES contient le contenu de la variable DEFINES à ce stade du fichier de projet. Cela équivaut également à :

MY_DEFINES = $${DEFINES}

La deuxième notation vous permet d’ajouter le contenu de la variable à une autre valeur sans séparer les deux par un espace. Par exemple, ce qui suit garantira que l’exécutable final portera un nom incluant le modèle de projet utilisé :

TARGET = myproject_$${TEMPLATE}

Fonctions de remplacement

qmake fournit une sélection de fonctions intégrées permettant de traiter le contenu des variables. Ces fonctions traitent les arguments qui leur sont fournis et renvoient une valeur, ou une liste de valeurs, en résultat. Pour attribuer un résultat à une variable, utilisez l’opérateur « $$ » avec ce type de fonction, comme vous le feriez pour attribuer le contenu d’une variable à une autre :

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

Ce type de fonction doit être utilisé à droite d’une affectation (c’est-à-dire en tant qu’opérande).

Vous pouvez définir vos propres fonctions pour traiter le contenu des variables comme suit :

defineReplace(functionName){
    #function code
}

La fonction d'exemple suivante prend un nom de variable comme seul argument, extrait une liste de valeurs de la variable à l’aide de la fonction intégrée `eval()` et compile une liste de fichiers :

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)
}

Fonctions de test

qmake fournit des fonctions intégrées pouvant être utilisées comme conditions lors de l'écriture de blocs. Ces fonctions ne renvoient pas de valeur, mais indiquent simplement si l'opération a réussi ou échoué:

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

Ce type de fonction ne doit être utilisé que dans des expressions conditionnelles.

Il est possible de définir vos propres fonctions pour fournir des conditions aux scopes. L'exemple suivant vérifie si chaque fichier d'une liste existe et renvoie « true » s'ils existent tous, ou « false » dans le cas contraire :

defineTest(allFiles) {
    files = $$ARGS

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