Add CMake introductive tutorial
This commit is contained in:
parent
4231795287
commit
74245adb5c
GPG Key ID:
1BBA026E13FC0495
|
|
@ -0,0 +1,349 @@
|
|||
# [Tutoriel] Compiler des add-ins avec CMake (fxSDK)
|
||||
|
||||
Ce tutoriel explique les bases de CMake et montre comment l'utiliser avec le fxSDK pour compiler des add-ins. L'objectif de ce tutoriel est de donner aux développeurs d'add-ins une compréhension minimale de la compilation de projets, pour vous permettre de maintenir le code lors des évolutions du fxSDK. C'est à la fois un tutoriel à lire de haut en bas et une référence à venir consulter quand vous aurez un doute dans la gestion de vos programmes. :)
|
||||
|
||||
Le fxSDK a longtemps utilisé un Makefile simple pour compiler les projets. Mais cela avait plusieurs inconvénients, essentiellement parce que les personnes débutant avec les add-ins n'avaient (à juste titre) pas envie ou pas le temps d'apprendre à le maîtriser, ce qui rendait son utilisation et sa mise à jour difficile. Le support de CMake a été introduit avec le fxSDK 2.3 pour résoudre ce problème, car il est plus accessible pour vous et bien plus pratique à maintenir pour moi.
|
||||
|
||||
Dans ce tutoriel, nous allons voir :
|
||||
|
||||
• [target=fichiers_et_commandes]Les fichiers et commandes utilisées pour compiler avec CMake[/target]
|
||||
• [target=langage_cmake]La syntaxe du langage CMake[/target]
|
||||
• [target=sources_cibles_dependances]Les sources, cibles et dépendances d'un système de compilation[/target]
|
||||
• [target=options_bibliotheques]Utiliser des options de compilation et des bibliothèques[/target]
|
||||
• [target=assets_g1a_g3a]La gestion des assets avec fxconv, les g1a et g3a[/target]
|
||||
• [target=systeme_minimal]Un système minimal fonctionnel[/target]
|
||||
• [target=defaut_fxsdk]L'add-in par défaut du fxSDK, pas-à-pas[/target]
|
||||
• [target=conclusion]Conclusion[/target]
|
||||
|
||||
C'est parti ! :D
|
||||
|
||||
[label=fichiers_et_commandes]
|
||||
[big][brown][b]Les fichiers et commandes utilisées pour compiler avec CMake[/b][/brown][/big]
|
||||
|
||||
Le fichier principal qui décrit comment votre add-in doit être compilé est `CMakeLists.txt`. Tout comme le Makefile qu'il remplace, c'est un fichier qui décrit quelles sont les sources, les cibles, et les options. :)
|
||||
|
||||
La commande `cmake` lance CMake, qui va lire `CMakeLists.txt` et générer un dossier de compilation avec un Makefile contenant les instructions (CMake ne compile pas lui-même). Une fois que c'est fait, on peut lancer `make` dans ce dossier pour compiler le projet.
|
||||
|
||||
Le dossier de compilation doit absolument être séparé, et du coup le dossier d'un add-in ressemblera généralement à ça (c'est par exemple le cas du projet par défaut du fxSDK) :
|
||||
|
||||
[code]MonAddIn
|
||||
├── assets-cg
|
||||
│ └── ... (les assets)
|
||||
├── assets-fx
|
||||
│ └── ... (les assets)
|
||||
├── build-cg
|
||||
│ └── ... (les fichiers compilés)
|
||||
├── build-fx
|
||||
│ └── ... (les fichiers compilés)
|
||||
├── CMakeLists.txt
|
||||
└── src
|
||||
└── ... (les sources)[/code]
|
||||
Le dossier `build-fx` est créé par CMake quand on compile pour Graph mono, et le dossier `build-cg` quand on compile pour Graph 90+E.
|
||||
|
||||
En principe, on peut lancer CMake avec la commande « `cmake . -B build` » pour compiler le projet situé dans le dossier courant (`.`) et stocker les fichiers compilés dans le dossier `build`. Mais, dans le cas de la calculatrice, il faut ajouter quelques informations en plus :
|
||||
|
||||
• D'abord il faut indiquer que le compilateur est `sh-elf-gcc`, avec quelques options ;
|
||||
• Et ensuite comme le fxSDK fournit des modules pour vous faciliter la tâche, il faut indiquer où les trouver.
|
||||
|
||||
Le fxSDK est programmé pour appeler `cmake` avec les bonnes options dans la commande `fxsdk build-fx`. S'il remarque que vous avez un `CMakeLists.txt` mais pas de dossier de compilation, il lance CMake puis make (pour les curieux, [url=https://gitea.planet-casio.com/Lephenixnoir/fxsdk/src/commit/70ff9ba6b8d7698b11ffe619b33d699cf6f65fc1/fxsdk/fxsdk.sh#L171]la commande complète est là[/url]). Si le dossier de compilation existe déjà, il lance juste make. Du coup dans vos projets vous n'aurez souvent besoin que de ces deux commandes.
|
||||
|
||||
[code]# Compiler pour Graph mono
|
||||
% fxsdk build-fx
|
||||
# Compiler pour Graph 90+E
|
||||
% fxsdk build-cg[/code]
|
||||
Sur ce, voyons voir comment `CMakeLists.txt` fonctionne et comment on peut compiler un projet avec.
|
||||
|
||||
[label=langage_cmake]
|
||||
[big][brown][b]La syntaxe du langage CMake[/b][/brown][/big]
|
||||
|
||||
`CMakeLists.txt` est une sorte de programme qui décrit votre projet en appelant des fonctions ou des modules. La syntaxe est la même pour tous les appels, et c'est quelque chose comme ça :
|
||||
|
||||
[code]nom_de_la_fonction(arg1 arg2 OPTION ARGUMENT valeur OPTION ...)[/code]
|
||||
Par exemple, la fonction `install()` permet de spécifier des fichiers à installer. Un appel peut ressembler à ça :
|
||||
|
||||
[code]install(FILES lib1.h lib2.h DESTINATION "${FXSDK_COMPILER_INSTALL}/include")[/code]
|
||||
Il y a deux arguments dans cet appel :
|
||||
• D'abord `FILES lib1.h lib2.h`, qui indique la liste des fichiers à installer.
|
||||
• Et ensuite `DESTINATION "${FXSDK_COMPILER_INSTALL}/include"`, qui indique où on les installe.
|
||||
|
||||
L'équivalent en Python aurait des arguments nommés et ressemblerait à ça :
|
||||
|
||||
[code]install(files=["lib1.h","lib2.h"], destination=f"{FXSDK_COMPILER_INSTALL}/include")[/code]
|
||||
`FILES` et `DESTINATION` sont des « mots-clés » de la fonction `install()`. Pour pouvoir lire la commande, il faut savoir quels sont les mots-clés pour découper au bon endroit. En général ce n'est pas difficile c'est les mots tout en majuscules ; la liste exacte est donnée dans la [url=https://cmake.org/cmake/help/latest/command/install.html#files]documentation de `install()`[/url]. Si vous avez un bon éditeur de texte, il les colorera automatiquement pour vous aider. ^^
|
||||
|
||||
Pour prendre un autre exemple, la fonction [url=https://cmake.org/cmake/help/latest/command/find_package.html]`find_package()`[/url] permet de rechercher une bibliothèque ou un outil sur l'ordinateur qui effectue la compilation. Un appel ressemblera à ça :
|
||||
|
||||
[code]find_package(Gint 2.1 REQUIRED)[/code]
|
||||
Iic il y a trois arguments :
|
||||
• D'abord le nom du paquet, « `Gint` », qui est toujours à la première place ;
|
||||
• Ensuite la version « 2.1 », qui doit être à la deuxième place si on l'indique ;
|
||||
• Et enfin l'option `REQUIRED`, indiquant que si gint n'est pas trouvé on veut émettre une erreur.
|
||||
|
||||
En Python, ça ressemblerait à ça :
|
||||
|
||||
[code]find_package("Gint", "2.1", required=True)[/code]
|
||||
Ces deux exemples montrent les quatre types d'arguments qu'on peut trouver dans les fonctions :
|
||||
• Les [i]arguments positionnels[/i] sont à une position fixe, et on donne directement la valeur : « `Gint` ».
|
||||
• Les [i]options[/i] sont des mots-clés pour activer ou désactiver des options : « `REQUIRED` ».
|
||||
• Les [i]arguments simples[/i] sont formés d'un mot-clé suivis d'une seule valeur : « `DESTINATION un_dossier` ».
|
||||
• Les [i]arguments multiples[/i] sont formés d'un mot-clé suivi d'une ou plusieurs valeurs : « `FILES lib1.h lib2.h` ».
|
||||
|
||||
Toutes les données sont des chaînes de caractères, mais quand il n'y pas de caractères spéciaux on n'est pas obligés de mettre les guillemets. On pourrait écrire `"FILES"` par exemple mais c'est plus léger d'éliminer les guillemets et d'écrire `FILES`. Les points, slashs et autre caractères qu'on trouve habituellement dans les noms de fichiers peuvent être utilisés sans guillemets. Personnellement j'en mets surtout quand il y a des variables à substituer dans la chaîne de caractères, par exemple dans `"${FXSDK_COMPILER_INSTALL}/include"`. La notation `${VAR}` sert à insérer la valeur d'une variable.
|
||||
|
||||
Au passage, on peut utliser `#` pour ajouter des commentaires qui continuent jusqu'à la fin de la ligne.
|
||||
|
||||
Avec ça vous devriez pouvoir déchiffrer les CMakeLists.txt sans trop de problèmes. On peut du coup s'attaquer au plat de résistance. ;)
|
||||
|
||||
[label=sources_cibles_dependances]
|
||||
[big][brown][b]Les sources, cibles et dépendances d'un système de compilation[/b][/brown][/big]
|
||||
|
||||
Les [b]sources[/b], les [b]cibles[/b] (“targets” en anglais), et les [b]dépendances[/b] sont trois grands concepts de tout système de compilation. Le but de la compilation est de compiler les sources pour produire les cibles, et de surveiller les dépendances pour recompiler le projet quand des changements sont faits.
|
||||
|
||||
Typiquement, dans un add-in écrit en C :
|
||||
• La cible est l'add-in final (le fichier .g1a ou .g3a).
|
||||
• Les sources sont les fichiers C que l'on veut compiler.
|
||||
• Les dépendances sont les fichiers C ainsi que les fichiers d'en-tête (les `.h`).
|
||||
|
||||
Le processus complet consiste à compiler les fichiers C pour produire l'add-in, et si une dépendance (un fichier C ou un en-tête) change, on recompile les fichiers C impactés (ceux qui ont changé ou qui incluent un en-tête qui a changé). ;)
|
||||
|
||||
Déclarer les cibles, les sources et les dépendances est le travail principal de votre `CMakeLists.txt`. En général vous n'avez pas besoin d'indiquer comment appeler GCC pour compiler puisque CMake sait déjà faire et le fxSDK a fourni les détails spécifiques à la calculatrice : il vous suffit de nommer les fichiers à compiler.
|
||||
|
||||
[b]Déclarer les cibles et les sources[/b]
|
||||
|
||||
Dans CMake, il y a trois types de cibles et chacun a une fonction servant à le déclarer.
|
||||
• Des exécutables : typiquement des logiciels ou des add-ins. On en crée avec [url=https://cmake.org/cmake/help/latest/command/add_executable.html]`add_executable()`[/url].
|
||||
• Des bibliothèques que vous pouvez réutiliser dans des exécutables. On en crée avec [url=https://cmake.org/cmake/help/latest/command/add_library.html]`add_library()`[/url].
|
||||
• Des cibles personnalisées, pour tout le reste. On en crée avec [url=https://cmake.org/cmake/help/latest/command/add_custom_target.html]`add_custom_target()`[/url].
|
||||
|
||||
Vous pouvez voir que le prototype de `add_executable()`, si on ignore les options utilisées plus rarement, est le suivant.
|
||||
|
||||
[code]add_executable(<name> [source1] [source2 ...])[/code]
|
||||
Le `<name>` est le nom de votre cible, il vous permet d'identifier la cible dans le reste de `CMakeLists.txt`. Par défaut, c'est aussi le nom du fichier exécutable. Il est entre chevrons donc c'est un argument obligatoire. Ensuite, il y a les sources ; les noms sont entre crochets donc elles sont facultatives (mais un exécutable vide ne sert à rien). Tous ces arguments sont positionnels, il n'y a pas de mot-clé ici.
|
||||
|
||||
Dans un add-in tout simple, on créerait le fichier exécutable avec une commande comme ci-dessous.
|
||||
|
||||
[code]add_executable(MonAddin src/main.c)[/code]
|
||||
Quasiment tout le système de compilation est contenu dans cette seule commande ! Pour que ça marche, il ne manque à indiquer que le fait de lier avec gint ou fxlib, et de générer le g1a/g3a (ce qui est fait par le fxSDK parce que CMake ne connaît pas ces formats). Je reviens sur ces points bientôt. ^^
|
||||
|
||||
Pour une bibliothèque, c'est presque pareil. Voici par exemple ce que fait [url=https://gitea.planet-casio.com/Lephenixnoir/libprof]libprof[/url] pour Graph mono :
|
||||
|
||||
[code]add_library(prof-fx STATIC libprof.c)[/code]
|
||||
Ici j'ai utilisé l'option `STATIC` pour créer une « bibliothèque statique ». Sinon CMake serait tenté de créer une « biblitothèque dynamique », un autre genre courant sur ordinateur mais bien plus compliqué et qu'on n'a pas sur la calculatrice.
|
||||
|
||||
Dans l'ensemble le principe est le même, et là aussi CMake gère toute la suite. Si vous regardez le prototype de `add_custom_target()` vous verrez que c'est un peu plus compliqué, c'est parce que cette fois vous devez indiquer les commandes à lancer pour produire la cible. Vous n'en aurez que rarement voire jamais besoin. ^^
|
||||
|
||||
[b]Déclarer les dépendances[/b]
|
||||
|
||||
Les dépendances ce sont les fichiers qui impactent le résultat de la compilation (on dit que le résultat de la compilation [i]dépend[/i] de ces fichiers). Chaque fois qu'une dépendance change, il faut recompiler pour s'assurer que le résultat est à jour.
|
||||
|
||||
Il y a plusieurs types de dépendances, souvent vous aurez affaire à une de celles-là :
|
||||
• Les dépendances qui affectent la compilation d'un fichier C sont ce fichier C, les en-têtes qu'il incluent, les en-têtes que ces en-têtes incluent, et ainsi de suite.
|
||||
• Les dépendances qui affectent la conversion d'un asset sont l'asset lui-même et ses métadonnées pour fxconv [i](j'y reviendrai)[/i].
|
||||
• Les dépendances qui affectent l'add-in final, en plus des sources et des assets, sont les bibliothèques, le `CMakeLists.txt`, et quelques autres détails.
|
||||
|
||||
La bonne nouvelle c'est que CMake s'occupe tout seul de déclarer la plupart de ces dépendances ! On n'a que très rarement besoin de le faire à la main. En particulier, le mécanisme un peu compliqué utilisé dans les Makefile pour rechercher les en-têtes inclus et obtenir les dépendances est géré tout seul par CMake. Dans votre `CMakeLists.txt` vous n'aurez quasiment jamais besoin de mentionner vos fichiers d'en-tête, car CMake va automatiquement les rechercher lorsqu'il liste les dépendances.
|
||||
|
||||
Si jamais vous avez besoin de déclarer des dépendances supplémentaires, jetez un oeil à [url=https://cmake.org/cmake/help/latest/command/set_source_files_properties.html]`set_sources_files_properties()`[/url] et [url=https://cmake.org/cmake/help/latest/command/set_target_properties.html]`set_target_properties()`[/url].
|
||||
|
||||
Comme vous pouvez le voir, la déclaration des sources, cible et dépendances ne demande pas beaucoup d'efforts en général. On va quand même s'attarder sur les options de compilation dont vous pourrez avoir besoin si votre projet grandit.
|
||||
|
||||
[label=options_bibliotheques]
|
||||
[big][brown][b]Utiliser des options de compilation et des bibliothèques[/b][/brown][/big]
|
||||
|
||||
Lorsque vous compilez un programme, vous pouvez modifier le comportement de GCC de différentes façons : afficher plus de warnings ou moins de warnings, activer des optimisations, choisir la version exacte du langage C que vous utilisez... tout cela se fait avec des options de compilation.
|
||||
|
||||
Dans CMake, les options de compilation sont définies pour une cible à l'aide de la fonction `target_compile_options()` qui a le prototype (simplifié) suivant :
|
||||
|
||||
[code]target_compile_options(<cible> <PUBLIC|PRIVATE|INTERFACE> <options...>)[/code]
|
||||
Le premier arguent est la cible à laquelle les options vont s'appliquer. Le deuxième indique dans quel contexte les options doivent être utilisées :
|
||||
• `PRIVATE` active les options durant la compilation de la cible (le cas de base) ;
|
||||
• `INTERFACE` active les options durant la compilation de fichiers qui [i]utilisent[/i] la cible (quand la cible est une bibliothèque) ;
|
||||
• `PUBLIC` fait les deux à la fois.
|
||||
|
||||
Et enfin, viennent les options sous la forme d'arguments en ligne de commande, par exemple `-Wall` pour activer (presque) tous les warnings, ou `-O2` pour optimiser le vitesse du programme au niveau 2. Dans le projet par défaut du fxSDK, on a les options suivantes :
|
||||
|
||||
[code]target_compile_options(myaddin PRIVATE -Wall -Wextra -Os)[/code]
|
||||
Cela active les options `-Wall`, `-Wextra` et `-Os`, qui activent un bon paquet de warnings et l'optimisation vitesse/taille du programme. `myaddin` est le nom de la cible, celui qui est donné comme premier argument à `add_executable()`. ;)
|
||||
|
||||
Pour les bibliothèques, c'est similaire. La différence est qu'il faut commencer par les trouver, ce qu'on fait avec la fonction [url=https://cmake.org/cmake/help/latest/command/find_package.html]`find_package()`[/url]. Son prototype (simplifié) est le suivant :
|
||||
|
||||
[code]find_package(<name> [version] [REQUIRED])[/code]
|
||||
Le premier argument est le nom de l'outil qu'on cherche ; le second (optionnel) est la version qu'on l'on souhaite utiliser, et si l'option `REQUIRED` est activée mais l'outil n'est pas trouvé CMake échouera avec une erreur. Si une version plus récente mais compatible avec celle demandée est trouvée, elle sera utilisée. Par exemple, un add-in qui utilise gint avec des fonctionnalités de la version 2.1 pourra indiquer :
|
||||
|
||||
[code]find_package(Gint 2.1 REQUIRED)[/code]
|
||||
Le paquet fournit ses propres cibles, dans le cas de gint il fournit une cible `Gint` que l'on désigne en la préfixant du nom du paquet, ce qui donne `Gint::Gint`. Pour compiler votre programme avec, utilisez [url=https://cmake.org/cmake/help/latest/command/target_link_libraries.html]`target_link_libraries()`[/url] :
|
||||
|
||||
[code]target_link_libraries(<cible> <bibliothèques...>)[/code]
|
||||
Un exemple tout simple pour lier avec gint serait donc :
|
||||
|
||||
[code]target_link_libraries(myaddin Gint::Gint)[/code]
|
||||
Vous pouvez spécifier plus d'une bibliothèque d'un coup, et vous n'êtes pas obligés d'utiliser des cibles CMake : vous pouvez écrire directement `-lsomelib` ou donner le nom d'un fichier `.a`, ça convient aussi tout à fait. ^^
|
||||
|
||||
Avec ça vous êtes parés pour accomplir à peu près toutes les tâches usuelles. Il nous reste un seul point supplémentaire spécifique aux add-ins sur la calculatrice à voir : la gestion des assets et la génération des fichiers g1a et g3a.
|
||||
|
||||
[label=assets_g1a_g3a]
|
||||
[big][brown][b]La gestion des assets avec fxconv, les g1a et g3a[/b][/brown][/big]
|
||||
|
||||
Les assets (images, polices, maps, dialogues, et autres données de votre application) ne sont pas gérés par CMake d'une façon aussi directe que `add_executable()`. Le fxSDK fournit des outils pour que ça reste transparent pour vous, mais je vais profiter de l'occasion pour détailler un peu comment créer des parties personnalisées dans le système de compilation. ;)
|
||||
|
||||
Un concept très utile de CMake des ces situations est les [i]modules[/i]. Vous pouvez inclure des fichiers externes dans votre `CMakeLists.txt`, y compris des fichiers distribués hors du projet. Le fxSDK fournit notamment :
|
||||
• `Fxconv.cmake` pour déclarer des assets à convertir avec fxconv.
|
||||
• `GenerateG1A.cmake` et `GenerateG3A.cmake` pour générer des fichiers g1a et g3a pour des exécutables.
|
||||
|
||||
On inclut un module avec la fonction [url=https://cmake.org/cmake/help/latest/command/include.html]`include()`[/url] qui est aussi simple que :
|
||||
|
||||
[code]include(<file|module>)[/code]
|
||||
Par exemple, le module `Fxconv.cmake` peut être inclus de la façon suivante (parce que le fxSDK [url=https://gitea.planet-casio.com/Lephenixnoir/fxsdk/src/commit/70ff9ba6b8d7698b11ffe619b33d699cf6f65fc1/fxsdk/fxsdk.sh#L172]indique à CMake[/url] que le dossier où `Fxconv.cmake` est stocké contient des modules).
|
||||
|
||||
[code]include(Fxconv)[/code]
|
||||
Actuellement ce module définit un nouveau langage `FXCONV` pour les assets, donc la commande de compilation appelle fxconv, et fournit une fonction `fxconv_declare_assets()` qui vous permet de lister vos fichiers d'assets pour qu'ils soient traités correctement par CMake.
|
||||
|
||||
Concrètement, pour traiter un fichier d'asset il faut faire deux choses :
|
||||
• Indiquer que son langage est `FXCONV` pour qu'il soit compilé avec fxconv et pas GCC ;
|
||||
• Indiquer une dépendance de l'asset vers le `fxconv-metadata.txt` du même dossier.
|
||||
|
||||
La dépendence existe car `fxconv-metadata.txt` (le fichier qui remplace le système bancal utilisé dans `project.cfg`) modifie les paramètres de la conversion, donc le résultat. Si on change les métadonnées, il faut reconvertir l'asset même si le fichier source (par exemple une image ou une police) n'a pas changé.
|
||||
|
||||
Ces deux informations (le langage et les dépendances d'un fichiers source) sont des propriétés du fichier source dans CMake, et on peut les modifier avec [url=https://cmake.org/cmake/help/latest/command/set_source_files_properties.html]`set_source_files_properties()`[/url]. Si vous êtes curieux, voici comment le module `Fxconv` modifie [url=https://gitea.planet-casio.com/Lephenixnoir/fxsdk/src/commit/0902fdc904c8e4f2f3145dfe58939a5ca5458ce1/fxsdk/cmake/Fxconv.cmake#L9]le langage[/url] et [url=https://gitea.planet-casio.com/Lephenixnoir/fxsdk/src/commit/0902fdc904c8e4f2f3145dfe58939a5ca5458ce1/fxsdk/cmake/Fxconv.cmake#L17]la dépendance[/url].
|
||||
|
||||
Et en fait c'est tout ! Les assets sont maintenant traités dans des fichiers sources dans `add_executable()` ou `add_library()` et seront simplement compilés avec fxconv au lieu de GCC. On peut donc mélanger les fichiers C et les assets et écrire :
|
||||
|
||||
[code]fxconv_declare_assets(assets-fx/example.png WITH_METADATA)
|
||||
add_executable(myaddin src/main.c assets-fx/example.png)[/code]
|
||||
La fonction `fxconv_declare_assets()` prend en paramètre une liste de fichiers d'assets. L'option `WITH_METADATA` ajoute la dépendance (c'est ce que vous voulez la plupart du temps).
|
||||
|
||||
Pour les fichiers g1a et g3a, c'est à peu près la même histoire, vous incluez le module et appelez la fonction qui convient pour générer un fichier g1a ou g3a après la compilation de votre exécutable.
|
||||
|
||||
[code]include(GenerateG1A)
|
||||
generate_g1a(TARGET <cible> [OUTPUT <fichier>] ...)[/code]
|
||||
La cible est le nom de votre cible exécutable (le premier argument de `add_executable()`). `OUTPUT` permet de choisir le nom du fichier de sortie ; et ensuite viennent les options du g1a, toutes facultatives :
|
||||
|
||||
• `NAME <nom>` pour indiquer le nom de l'add-in dans le menu SYSTEM ;
|
||||
• `INTERNAL <nom interne>` pour indiquer le nom interne (en général vous n'avez pas besoin de l'indiquer) ;
|
||||
• `VERSION <MM.mm.pppp>` pour donner la version du programme ;
|
||||
• `DATE <YYYY.mmdd.hhmm>` pour la date de compilation (la valeur par défaut est la date du jour) ;
|
||||
• `ICON <image>` pour choisir l'icône (qui doit être un fichier PNG de 30x19 pixels).
|
||||
|
||||
[code]include(GenerateG3A)
|
||||
generate_g3a(TARGET <cible> [OUTPUT <fichier>] ...)[/code]
|
||||
Le fonctionnement pour les g3a est identique. Il y a un peu moins d'options car mkg3a ne donne pas accès à tous les détails :
|
||||
|
||||
• `NAME <nom>` pour indiquer le nom de l'add-in. Le nom est aussi affiché sur le menu principal, mais parfois on n'en veut pas. Vous pouvez indiquer un nom vide en écrivant « `NAME ""` » pour que l'icône soit affichée sans texte par dessus.
|
||||
• `ICONS <icone-unselected> <icon-selected>` pour donner les icônes (deux images PNG de 92x64 pixels).
|
||||
|
||||
Voilà ce que ça donne dans le projet par défaut. :)
|
||||
|
||||
[code]# Pour Graph mono
|
||||
generate_g1a(TARGET myaddin OUTPUT "MyAddin.g1a" NAME "MyAddin"
|
||||
ICON assets-fx/icon.png)
|
||||
# Pour Graph 90+E
|
||||
generate_g3a(TARGET myaddin OUTPUT "MyAddin.g3a" NAME "MyAddin"
|
||||
ICONS assets-cg/icon-uns.png assets-cg/icon-sel.png)[/code]
|
||||
|
||||
[label=systeme_minimal]
|
||||
[big][brown][b]Un système minimal fonctionnel[/b][/brown][/big]
|
||||
|
||||
Avec ça, on peut maintenant compiler un add-in pour de vrai ! Voici le plus petit système de compilation d'add-in pour Graph mono avec CMake. ;)
|
||||
|
||||
[code]cmake_minimum_required(VERSION 3.18)
|
||||
project(MyAddin)
|
||||
|
||||
include(GenerateG1A)
|
||||
include(Fxconv)
|
||||
find_package(Gint 2.1 REQUIRED)
|
||||
|
||||
fxconv_declare_assets(assets-fx/example.png)
|
||||
add_executable(myaddin src/main.c assets-fx/example.png)
|
||||
|
||||
target_compile_options(myaddin PRIVATE -Wall -Wextra -Os)
|
||||
target_link_libraries(myaddin Gint::Gint)
|
||||
|
||||
generate_g1a(TARGET myaddin OUTPUT "MyAddin.g1a" NAME "MyAddin"
|
||||
ICON assets-fx/icon.png)[/code]
|
||||
Comme vous pouvez le voir, c'est simplement un combinaison de tout ce qu'on a vu jusqu'ici. Il n'y a que deux nouveautés dont il faut s'occuper au début de `CMakeLists.txt` : d'abord [url=https://cmake.org/cmake/help/latest/command/cmake_minimum_required.html]`cmake_minimum_required()`[/url] pour indiquer la version de CMake que vous suivez (les fonctions ont changé au cours du temps), et puis [url=https://cmake.org/cmake/help/latest/command/project.html]`project()`[/url] pour nommer le projet (on peut aussi donner sa version et indiquer les langages si besoin).
|
||||
|
||||
Vous pouvez coller ça dans votre `CMakeLists.txt` et lancer `fxsdk build-fx`, vous aurez votre `MyAddin.g1a`. :)
|
||||
|
||||
[label=defaut_fxsdk]
|
||||
[big][brown][b]L'add-in par défaut du fxSDK, pas-à-pas[/b][/brown][/big]
|
||||
|
||||
Le `CMakeLists.txt` que le fxSDK vous donne dans les nouveaux projets est un poil plus compliqué (il permet notamment de compiler pour Graph mono et Graph 90+E), alors voici les détails pas-à-pas ! Le début commence exactement comme on l'attend, en incluant les modules et gint.
|
||||
|
||||
[code]# Configure with [fxsdk build-fx] or [fxsdk build-cg], which provide the
|
||||
# toolchain file and module path of the fxSDK
|
||||
|
||||
cmake_minimum_required(VERSION 3.18)
|
||||
project(MyAddin)
|
||||
|
||||
include(GenerateG1A)
|
||||
include(GenerateG3A)
|
||||
include(Fxconv)
|
||||
find_package(Gint 2.1 REQUIRED)[/code]
|
||||
Ensuite on définit quelques variables pour spécifier les fichiers sources, les assets communs Graph mono/Graph 90+E, les assets spécifiques à la Graph mono, et les assets spécifiques à la Graph 90+E.
|
||||
|
||||
[code]set(SOURCES
|
||||
src/main.c
|
||||
# ...
|
||||
)
|
||||
# Shared assets, fx-9860G-only assets and fx-CG-50-only assets
|
||||
set(ASSETS
|
||||
# ...
|
||||
)
|
||||
set(ASSETS_fx
|
||||
assets-fx/example.png
|
||||
# ...
|
||||
)
|
||||
set(ASSETS_cg
|
||||
assets-cg/example.png
|
||||
# ...
|
||||
)[/code]
|
||||
Je n'ai pas encore parlé des variables même si quelques-unes sont utilisées dans les exemples précédents. C'est assez direct :
|
||||
• On peut créer ou modifier une variable avec [url=https://cmake.org/cmake/help/latest/command/set.html]`set()`[/url] : `set(<nom> <valeur>)`.
|
||||
• On peut obtenir la valeur d'une variable avec `${nom}` (en général entre guillemets pour ne pas être embêté s'il y a des espaces ou points-virgules dans les contenus).
|
||||
|
||||
Voici un exemple tout simple. [url=https://cmake.org/cmake/help/latest/command/message.html]`message()`[/url] est juste un print, c'est utile pour debugger :
|
||||
|
||||
[code]set(MA_VARIABLE "du texte")
|
||||
message("MA_VARIABLE contient ${MA_VARIABLE}")[/code]
|
||||
Ce code affiche "MA_VARIABLE contient du texte" quand CMake est lancé.
|
||||
|
||||
Dans le projet, on utilise une fonctionnalité de `set()` qui permet de spécifier plusieurs valeurs pour faire une « liste » ; c'est une fausse liste, les valeurs sont juste séparées par des points-virgules.
|
||||
|
||||
[code]set(SOURCES src/main.c src/game.c)
|
||||
message("${SOURCES}") # -> affiche "src/main.c;src/game.c"[/code]
|
||||
Ensuite on déclare les assets, comme précédemment.
|
||||
|
||||
[code]fxconv_declare_assets(${ASSETS} ${ASSETS_fx} ${ASSETS_cg} WITH_METADATA)[/code]
|
||||
Ici on ne met pas de guillemets autour des variables, c'est fait exprès : comme ça la liste sera « déroulée » en une liste d'arguments (un peu comme `fonction(*liste)` en Python). Si ça vous échappe ne vous inquiétez pas trop. ^^
|
||||
|
||||
Ensuite, on crée la cible exécutable. C'est là qu'on voit apparaître des différences entre Graph mono et Graph 90+E. Ce dont il faut se souvenir c'est que le `CMakeLists.txt` sera exécuté deux fois : une fois pour Graph mono quand on utilise `fxsdk build-fx`, et une fois pour Graph 90+E quand on utilise `fxsdk build-cg`. Il n'y a donc besoin de se soucier que d'une seule plateforme à la fois, et le fxSDK indique laquelle avec deux variables :
|
||||
|
||||
• `FXSDK_PLATFORM` vaut « `fx` » quand on compile pour Graph mono et « `cg` » quand on compile pour Graph 90+E.
|
||||
• `FXSDK_PLATFORM_LONG` vaut « `fx9860G` » quand on compile pour Graph mono et « `fxCG50` » quand on compile pour Graph 90+E.
|
||||
|
||||
La deuxième est plus lisible mais la première est pratique dans certains cas. Par exemple, dans la cible exécutable qu'est notre add-in, on veut ajouter uniquement les assets de la platforme courante, ce qu'on peut faire élegamment avec `FXSDK_PLATFORM`.
|
||||
|
||||
[code]add_executable(myaddin ${SOURCES} ${ASSETS} ${ASSETS_${FXSDK_PLATFORM}})
|
||||
target_compile_options(myaddin PRIVATE -Wall -Wextra -Os)
|
||||
target_link_libraries(myaddin Gint::Gint)[/code]
|
||||
Tout comme dans `fxconv_declare_assets()`, on passe les listes de sources et assets en argument (donc sans guillemets). `${ASSETS_${FXSDK_PLATFORM}}` devient `${ASSETS_fx}` ou `${ASSETS_cg}` selon la plateforme pour laquelle on compile, ce qui permet de choisir élégamment la bonne liste d'assets. Les sources de la cible sont donc les fichiers C, les assets communs, et les assets spécifiques à la plateforme à laquelle on est en train de s'intéresser.
|
||||
|
||||
Ensuite on ajoute les options de compilation et on linke avec gint, rien d'inattendu ici.
|
||||
|
||||
[code]if("${FXSDK_PLATFORM_LONG}" STREQUAL fx9860G)
|
||||
generate_g1a(TARGET myaddin OUTPUT "MyAddin.g1a"
|
||||
NAME "MyAddin" ICON assets-fx/icon.png)
|
||||
elseif("${FXSDK_PLATFORM_LONG}" STREQUAL fxCG50)
|
||||
generate_g3a(TARGET myaddin OUTPUT "MyAddin.g3a"
|
||||
NAME "MyAddin" ICONS assets-cg/icon-uns.png assets-cg/icon-sel.png)
|
||||
endif()[/code]
|
||||
Et enfin on génère un fichier g1a ou g3a. On utilise [url=https://cmake.org/cmake/help/v3.19/command/if.html]`if()`[/url] pour tester la plateforme, et on utilise `generate_g1a()` ou `generate_g3a()` selon le cas. La syntaxe du if n'est pas vraiment intuitive, on ne peut pas écrire des conditions avec `==`, `<=` ou `!=` comme dans les langages de programmation ; à la place il faut tester avec des mots-clés comme `STREQUAL`. C'est un peu comme `test` en bash (pour ceux qui connaissent). Dans l'ensemble, consultez la documentation en cas de doute.
|
||||
|
||||
Et voilà, vous savez maintenant comment `CMakeLists.txt` fonctionne dans votre add-in, et vous êtes équipé·e pour aborder sereinement sa modification pour répondre à vos besoins futurs. ;)
|
||||
|
||||
[label=conclusion]
|
||||
[big][brown][b]Conclusion[/b][/brown][/big]
|
||||
|
||||
CMake est un système de compilation riche et avec sa part de complexité, mais qui présente aux débutants des moyens simples et directs pour gérer la compilation de programmes. Dans ce tutoriel, on a vu comment un add-in pour la calculatrice pouvait se compiler avec CMake et le fxSDK, en couvrant tant le code source que les assets, les options de compilation, et l'utilisation de bibliothèques.
|
||||
|
||||
J'espère que ce tutoriel vous aura permis de comprendre et maîtriser votre système de compilation, et ainsi de vous faciliter la gestion de projet au cours des évolutions à la fois de vos programmes et des outils comme le fxSDK. ;)
|
||||
Loading…
Reference in New Issue