Bonjour mes Petits

Nous nous retrouvons donc réunis comme prévu dans mon atelier pour mener à bien ce tout premier épisode de notre série de tutos.

Liens vers l'ensemble des articles de la série

Cliquer pour enrouler

Pour rappel, les liens qui vont bien pour la série [c'est du WIP donc ce sera complété au fur et à mesure]:
- Introduction de la série
- Tuto #1 - Présentation du fxSDK et du wording associé
- Tuto #2 - Présentation en détail du jeu et premier prototype
- Tuto #3 - On entre dans le vif du sujet, un premier truc qui ressemble à un jeu
- Tuto #4 - Quand ça va mal, qu'est ce qu'on fait ? Car ça arrive toujours à un moment ou à un autre
- Tuto #5 - On ajoute quelques notions avancées

Le but sera aujourd'hui dans un premier temps de bien comprendre ce que contient le fxSDK en termes d'outils et d'expliquer le rôle de chacun. Cela pouvant être un peu difficile de s'y retrouver pour les nouveaux arrivants, il est donc intéressant de s'attarder un peu sur cette description et de bien poser les bases.
Le projet de jeu de Tower Defense sera codé en C++ (pas en C), il nous faudra donc spécifiquement modifier les paramétrages du projet pour autoriser l'utilisation du langage C++. Nous passerons donc du temps pour opérer ces changements et expliciter le rôle de chacune des modifications apportée. Là encore, le temps passé aujourd'hui sur cet aspect sera très certainement une aide pour vos projets futurs.

Autant être honnête dès à présent, ce ne sera certainement pas aujourd'hui l'épisode le plus sexy de la série, mais il aura au moins le mérite de poser de bonnes bases pour la suite. J'espère qu'il répondra aussi à de nombreuses questions que beaucoup se sont posées sans jamais oser demander

Bon donc c'est parti, soyez les bienvenus dans ce premier volet de la série intitulé :

Présentation du fxSDK et du wording associé

Tout d'abord pour introduire le sujet sans plagier la description ce qui a été dit par Lephenixnoir dans de précédents tutos, il faut rappeler ce qu'est un SDK et en particulier celui qui nous intéresse présentement. Un SDK, ou Software Development Kit (ie. Kit de Développement Logiciel dans la langue de Molière), est comme son nom l'indique, une collection d'outils dédiés à la création de logiciels pour une machine ou une architecture donnée. Avec ce dit kit, on sera en mesure de créer un logiciel (un jeu, un utilitaire, ...) qui fonctionnera sur la machine cible. Il contient donc divers logiciels permettant de convertir, programmer, compiler, transférer, ... des ressources en un programme capable de fonctionner sur la machine cible.

En l'occurrence, le fxSDK vise à proposer les outils nécessaires pour les calculatrices Casio basées sur des processeurs Renesas SuperH (SH3 et SH4). Cela fait une longue liste de machines supportées, tant à écrans couleurs comme les Prizm (fx-CG10, fx-CG20 et fxCG-50 / Graph 90+E) que les machines à écrans monochromes (fx9860GI/II/III ou Graph 35/35+/35+E/35+EII ainsi que Graph75/85/95 SD ou non). Bref, un large spectre pour vous faire plaisir. Un joli exemple de réalisation de projet transverse multi-machine est le projet collaboratif de l'été 2023 illustré par cette image:



Nous verrons donc dans une première section de ce tuto quels sont les outils disponibles dans fxSDK et quel est le rôle de chacun des composants. Nous en profiterons aussi pour détailler (un peu) les deux projets compagnons que sont gint et FxLibc qui constituent la fondation de vos programmes.

Nous regarderons alors plus dans le détail 2 fichiers très importants dans tout projet fxSDK et qui seront les chefs d'orchestre de la compilation de vos futurs programmes, à savoir les fichiers CMakeLists.txt et fxconv-metadata.txt.

Nous verrons enfin comment créer notre premier projet et nous le configurerons ensemble pour répondre à nos besoins spécifiques avant de compiler cet add-in "à blanc" et vérifier que tout fonctionne comme prévu.

Allez, c'est parti alors. Après ce blah-blah introductif, entrons dans le vif du sujet ...


a. Les différents outils du SDK (fxsdk, fxconv, fxgxa/fxg1a, fxlink ) qui fait quoi ?

Partons sur l'hypothèse que vous avez bien installé le fxSDK tel que préconisé dans le fil dédié ici en utilisant la méthode basée sur GiteaPC. Vous devriez vous retrouver avec dans votre répertoire /home/xxxxx/.local/bin (xxxxx étant votre nom d'utilisateur, il va sans dire) avec un certain nombre d'exécutables et ou de liens symboliques reliés aux outils du fxSDK. Voici dans mon cas ce que je peux trouver dans ce dit répertoire (commande ls -la pour information):



On peut voir entre autres toute une série de liens symboliques dont le nom est sh-elf-xxx et pointant vers le compilateur de GCC (mais si vous savez, le truc qui a compilé durant une plombe lors de l'installation du SDK ), ainsi que divers exécutables dont le nom commence par "fx". Ces derniers sont les outils proposés par fxSDK et pour lesquels nous allons apporter une explication détaillée.
En lisant ce paragraphe, une information importante est apparue, à savoir que le fxSDK repose sur le compilateur GCC. J'ouvre donc une rapide parenthèse : en effet, lors de l'installation du fxSDK et de ses dépendances, une version spécifique du compilateur GCC a été installée et configurée sur votre machine de manière à être en capacité de compiler du code machine pour l'architecture SuperH. Si vous aviez déjà GCC d'installé sur votre PC, sachez que ce sont deux installations complètement indépendantes. On parle alors de "Toolchain" et le système ne mélangera pas les installations (du moins en théorie).


Tout d'abord, fxsdk est un script qui permet de créer et de compiler les projets.

Pour créer un nouveau projet, il suffit de lancer la commande fxsdk new nom_du_projet dans un répertoire qui vous est accessible en écriture et fxsdk va créer un sous-répertoire intitulé nom_du_projet dans lequel seront placés tous les éléments de base pour débuter un projet. Il s'agit donc de la toute première opération à faire lorsque l'on désire débuter un nouveau projet. L'image suivante vous montre la capture de la commande et le détail des fichiers créés par fxSDK dans le sous-répertoire du projet.



Il est intéressant de lire les lignes retournées par fxSDK lors de la création du projet. En effet, fxSDK nous indique que le projet sera "buildé" via CMake. Ceci est désormais le fonctionnement par défaut, mais pour les plus velus d'entre vous, sachez qu'il est possible de générer un build via un Makefile.

Un coup de commande tree permet de lister les sous-répertoires et les fichiers dans ce projet minimal (qui est grosso modo un "hello world"). Mais nous y reviendrons un peu plus tard.

A ce stade, tout est disponible pour démarrer un projet soit destiné aux Graph couleurs, soit aux Graph monochromes. Afin de faciliter l'écriture de cette série de tutos, j'utiliserai à partir de maintenant l'abréviation "fxCG" pour les Graphs couleurs et "fx9860G" pour les Graphs monochromes.

Le projet en l'état est donc tout à fait buildable et on peut donc lancer une compilation telle quelle afin de tester que tout va bien via les commandes suivantes (qui sont précisées par le message de fxsdk à la création du projet) :
- fxsdk build-fx afin de générer un add-in au format g1a utilisable sur les fx9860G
- fxsdk build-cg afin de générer un add-in au format g3a utilisable sur les fxCG

Par défaut, les fichiers source compilés (fichier.c --> fichier.o) qui n'ont pas été modifiés ne sont pas recompilés. Cela permet de gagner pas mal de temps, mais crée parfois quelques couacs. On peut donc être amenés à devoir forcer la main au système. Pour ce faire, il suffit de rajouter une option -B pour forcer le rebuild intégral (par exemple fxsdk build-cg -B). Pour faire apparaître tous les détails durant la compilation (on dit passer en mode verbeux), on peut aussi rajouter l'option VERBOSE=1 afin d'avoir les lignes de compilations détaillées (cela sert souvent quand on cherche à comprendre un problème).

Voici une capture de la sortie de compilation en mode normal :


et la même chose en mode verbeux :


On retrouve toutes les infos du mode normal, mais noyées au milieu de très nombreuses lignes supplémentaires indiquant tout le détail du processus de compilation.

Il existe quelques autres options pour le script fxsdk, mais elles sont de moindre importance, nous ne les traiterons donc pas ici.


Le second outil présent dans le kit est fxconv dont le but, comme son nom l'indique, est d'opérer des conversions.

fxconv dispose d'un certain nombre de modules permettant par exemple de récupérer des images et de les convertir vers les formats utilisables dans votre code source, ou d'importer des polices de caractères personnelles afin de customiser vos projets. Mais fxconv est surtout capable, via l'ajout de convertisseurs ad-hoc personnels écrits en Python, de convertir à peu près n'importe quoi pour le rendre utilisable dans vos programmes sur calculatrice. Parmi les trucs cools vus passer, on peut citer :
- l'importation de fichiers issus de l'éditeur de niveaux Tiled avec support de multiples couches (ie. layers),
- l'importation de fichiers issus de Aseprite/Libresprite avec support des animations,
- l'importation de fichiers de niveaux, de fichiers obj issus de Blender par exemple, ...
Bref, un outil très utile une fois qu'on a bien pris le temps de l'étudier. Seule votre imagination vous limitera avec cet outil dans les mains et un peu de pratique.

Pour un premier projet, on considérera fxconv comme une boîte noire, mais si le besoin s'en fait sentir, nous pourrons parler plus spécifiquement de cet outil dans un tuto dédié dans le futur, quand nous aurons plus avancé dans les tutos.


fxgxa crée les fichiers g1a (format des add-ins fx9860G) et g3a (format des add-ins fxCG) à partir des programmes compilés.

fxgxa (et le lien symbolique fxg1a) ont pour rôle de récupérer le code exécutable généré par le compilateur et le linkeur (le "binaire" ou .bin) et de le rendre compatible et utilisable sur les machines Casio. Pour ce faire, le binaire doit être "habillé" de tout un tas de data (entête, calcul de checksum de validité, données représentant les icônes visibles dans le menu principal de vos machines, ...). Cette conversion est réalisée par fxgxa. Les interactions avec fxgxadu point de vue du programmeur sont assez limitées, mais on peut néanmoins préciser quelques données qui seront passées à fxgxa et qui de fait permettrons de finement ajuster nos add-ins (images représentant les icônes dans le menu, nom du programme, nom à afficher, numéro de version). Nous verrons cela en temps et en heure.

Si vous remontez quelques années en arrière dans le forum, vous trouverez peut-être des références à l'outil mkg3a, qui est le programme précédent qui faisait cette conversion pour les fxCG ou a fxg1a qui faisait la conversion pour fx9860G. Désormais fxgxa permet d'avoir un seul utilitaire pour les 2 cibles. Le lien symbolique fxg1a dont nous parlions précédemment point vers fxgxa et est présent pour des questions de rétrocompatibilité.


Enfin, dernier de la liste, mais pas le moindre en terme d'importance, fxlink est un outil permettant de communiquer entre votre PC et votre calculatrice et qui peut par exemple transférer des fichiers vers les Graph 35+E II et Graph 90+E en ligne de commande, mais aussi permettre à un add-in d'interagir avec votre PC. On peut par exemple envoyer des captures d'écran ou faire de la capture vidéo via gint avec un câble USB connecté au PC.

Historiquement, seule la communication dans le sens Calculatrice --> PC était possible, mais récemment, Lephenixnoir a repris complètement le driver USB et permis la mise en place la communication bidirectionnelle. Une démonstration très impressionnante de ce que l'on peut faire avec cet outil est donnée par la vidéo suivante:



Même si les outils qui vont suivre ne font pas explicitement partie du fxSDK, il est important de les citer car ils sont plus ou moins nécessaires au fonctionnement de vos projets ou vous faciliterons énormément la vie:

- giteapc est un script python permettant d'automatiser l'installation des programmes et des librairies depuis la forge Gitea de Planète Casio. Cet outil permet notamment d'installer des versions spécifiques (par exemple les versions de développement) de vos librairies ou de vos programmes et de maintenir à jour de manière simple votre toolchain de développement Casio.

- FxLibc est une librairie dont le rôle est de donner accès aux fonctions standards du C. On appelle d'ailleurs cette librairie la "librairie standard du C". Il s'agit de la retranscription la plus fidèle possible pour les machines Casio, des fonctions de base offertes par le langage C (printf(), scanf(), malloc(), ...). Il s'agit donc du socle premier sur lequel repose la plupart des programmes.

- gint est un micro-noyau monolithique (micro unikernel) permettant de faire la liaison entre les programmes et le matériel en apportant les drivers nécessaires au système. Cela permet par exemple de dessiner à l'écran, d'ouvrir le port USB, de récupérer les touches enfoncées ... Bref dès que l'on veut une interaction avec le matériel, il y a gint qui opère en arrière-plan.

Nous voici donc au bout de cette longue description, nous allons donc pouvoir attaquer les choses un peu plus concrètes et sérieuses.


b. Une explication du rôle des répertoires et des fichiers CMakeLists.txt et fxconv-metadata.txt

Maintenant que nous avons fait le tour des outils, passons à l'analyse des dossiers et fichiers présents dans un projet. Prenons l'exemple du projet de base :



A la racine de celui-ci, on trouve un seul fichier nommé CMakeLists.txt qui comme son nom l'indique est un fichier destiné à CMake. Il s'agit du fichier dans lequel vous pourrez piloter la gestion des fichiers source, des fichiers de ressources (ou assets) ainsi que les diverses options de compilation, de linkage, le nom de votre add-in, etc.

C'est donc un fichier central sur lequel vous aurez à intervenir extrêmement souvent. Il s'agit du pendant du fichier Makefile pour l'outil make.

On retrouve de base 3 répertoires dans la structure :
- src : qui contient les fichiers source, c'est-à-dire le code que vous allez écrire dans le cadre de votre programme,
- asset-cg: qui contient les ressources (assets) pour la fxCG (les images, les polices de caractère, les icônes ...) associées à un fichier fxconv-metadata.txt
- asset-fx: qui contient les ressources (assets) pour la fx9860G (les images, les polices de caractère, les icônes ...) elles aussi associées à un fichier fxconv-metadata.txt

Les fichiers fxconv-metadata.txt permettent de faire la liaison entre le fichier CMakeLists.txt vu précédemment, les ressources contenues dans le répertoire courant et l'outil fxconv. Il est destiné à préciser à fxconv divers paramètres pour mener à bien la conversion de chacune des ressources. Cela peut paraître un peu obscur, mais nous allons expliciter par un exemple rapidement par la suite.

Il est tout à fait possible d'organiser un projet différemment, ou de rajouter des sous-répertoires, notamment lorsque les projets deviennent importants en taille. L'important étant pour vous de vous y retrouver et surtout de bien indiquer à travers les fichiers CMakeLists.txt et fxconv-metadata.txt où se trouvent tous les éléments nécessaires à la bonne conduite du processus de compilation. Voici par exemple la structure d'un projet moyen en taille, mon jeu de Pinball. On retrouve globalement cette structure (sans assets-fx car le jeu est exclusif à la fxCG) et un détail dans le répertoire src :



Après compilation de notre exemple de projet Tower Defense, par exemple pour la Graph 90+E, donc en lançant la commande fxsdk build-cg on obtient l'arborescence suivante :



On note d'une part l'apparition d'un nouveau répertoire build-cg avec de très nombreux sous-répertoires et fichiers (j'ai volontairement limité la portée de la commande tree afin de ne pas surcharger l'image). Ce sous-répertoire contient l'ensemble des fichiers créés durant le processus de compilation et de linkage. On y trouve notamment le fichier binaire contenant le code machine compréhensible par le processeur SuperH (mais attention, pas par l'OS).

Et à la racine, on trouve le fichier g3a correspondant à notre add-in qui lui est reconnu par l'OS de nos machines. Il s'agit du fichier final généré par l'outil fxgxa à partir du fichier binaire et avec l'habillage attendu par l'OS pour être géré correctement.

Voilà qui en termine avec le tour d'horizon de la structure des fichiers et répertoires d'un projet type fxSDK. Passons donc désormais au paramétrage concret de ce projet.


c. Création d'un premier projet et mise en place du paramétrage de base

Notre projet vise à être écrit en C++, il nous faut donc configurer les paramètres adéquats dans CMakeLists.txt, car le langage par défaut des projets fxSDK est le C. On va donc profiter de l'occasion pour ajuster ce fichier, en y apportant les modifications nécessaires. Voici ci-après le fichier original que nous allons modifier


La première chose à intégrer est la mise en place de la possibilité d'utiliser le C++. Il y a plusieurs lignes à modifier :

Indiquer le langage dans le projet via la lignequ'il faut changer en
D'une part on met un nom de projet plus adéquat, mais on profite pour ajouter les langages pouvant être présents (ici C, C++ (attention il faut écrire CXX) et potentiellement ASM)

Attention, il faut aussi ajouter un paramètre sur la lignepour définir quelle version du langage C++ on va retenirici on va se baser sur le standard C++20 qui est l'un des plus récents et offre énormément de fonctionnalités.

Il faut aussi pouvoir utiliser la librairie standard du C++ qui apporte beaucoup d'améliorations (les std::string, les différents conteneurs (std::vector, std::list, std::map, etc. ) et plein d'algorithmes utiles, comme par exemple des algorithme de tri, de générations de nombres aléatoires, etc.). Pour ce faire il faut changer la ligneet la remplacer par

Enfin, profitons de l'occasion pour ajuster le nom des fichiers g1a et g3a et des titres des add-ins pour les deux machines (fx9860G et fxCG respectivement) dans la toute dernière section du fichier.à remplacer par :

A ce stade, on a tout bien configuré et on est OK pour faire du C++. Mais comme je suis un vieux Papy, j'ai mes petites habitudes et personnellement, j'aime reconnaître avec l'extension des fichiers source si je travaille en C ou en C++. Je procède donc avec la convention suivante :
- les fichiers source en C portent l'extension ".c" et les fichiers headers en C portent l'extension ".h"
- les fichiers source en C++ portent l'extension ".cpp" et les fichiers headers en C++ portent l'extension ".hpp"

Je vais donc renommer le fichier main.c en main.cpp, en changeant bien la ligne correspondante dans le fichier CMakeLists.txt:devient :

Au final, on se retrouve donc avec le fichier CMakeLists.txt suivant :


Afin de tester un code C++, je vous propose de coller le code suivant dans votre fichier main.cpp en lieu et place du code existant :

De sauvegarder les modifications, puis de compiler depuis la racine de votre projet en faisant un fxsdk build-cg ou fxsdk build-fx

Vous pouvez ensuite tranférer l'add-in obtenu sur votre machine et le lancer.

Oh miracle, vous avez programmé votre premier add-in en C++ fonctionnel.

Voici sur Graph 90+E ce que cela donne (ma version contient des couleurs pour illustrer, mais le code fournit sortira en noir pour être compatible avec la fx9860G, donc pas de panique ).



Voilà qui en termine avec ce très long tuto, pas forcément le plus fun, mais qui j'espère vous aura permis de mieux comprendre comment fonctionne le fxSDK. Notre architecture de projet est désormais en place, dûment configurée, on va donc pouvoir commencer à s'amuser dès le prochain épisode et attaquer le développement de notre petit jeu.

Vous trouverez dans le fichier ZIP attaché une copie du projet dûment configuré et fonctionnel. N'hésitez pas à poster vos questions et/ou vos commentaires. Je tâcherai de répondre à tous vos posts.

On se retrouve donc très rapidement pour le prochain épisode de cette série de tutos, gardez un œil bien ouvert sur la page d'accueil et guettez bien le retour de Papy Sly.

C'est pas tout ça, je vais aller me faire une camomille ...

A très bientôt mes Petiots

Papy Sly


Edit 25/01/2023 : corrigé quelques typos qui étaient passées entre les mailles du filet

Fichier joint