RECORDFILE et gestion de projets Forth
publication: 8 mai 2026 / mis à jour 8 mai 2026
Enregistrer RECORDFILE dans le fichier autoexec.fs
Voici étape par étape comment enregistrer la définition de RECORDFILE, puis l’utiliser de manière efficace.
Au démarrage de ESP32forth, le système teste la présence du fichier autoexec.fs. Si ce fichier est présent, son contenu sera interprété.
Voici le code source de RECORDFILE. Cette définition a été mise au point par Bob EDWARDS.
Copiez ce code et collez le dans la fenêtre du terminal pour le compiler. Cette manœuvre ne sera
à exécuter qu’une seule fois :
\ These chars terminate all text lines in a file create crlf 13 C, 10 C, \ Records the input stream to a spiffs file until \ an <EOF> marker is encountered, then close file : RECORDFILE ( "filename" "filecontents" "<EOF>" -- ) bl parse \ read the filename ( a n ) W/O CREATE-FILE throw >R \ create the file to record to - \ put file id on R stack BEGIN \ read a line of the file from the input stream tib #tib accept tib over S" <EOF>" startswith? \ does the line start with <EOF> ? DUP IF \ Yes, so drop the end line of the file containing <EOF> swap drop ELSE swap tib swap \ No, so write the line to the open file R@ WRITE-FILE throw \ and terminate line with cr-lf crlf 2 R@ WRITE-FILE throw THEN UNTIL \ repeat untilfound R> CLOSE-FILE throw \ Close the file ;
Une fois ce mot compilé, on va voir comment procéder pour que ce mot soit disponible en permanence depuis autoexec.fs.
Sur votre PC, dans votre espace de développement dédié à ESP32Forth, créez un fichier autoexec.fs.
Copiez dans ce fichier autoexec.fs le code de RECORDFILE tel que donné ci-avant.
Rajoutez ces deux lignes de code :
RECORDFILE /spiffs/autoexec.fs \ These chars terminate all text lines in a file create crlf 13 C, 10 C, \ Records the input stream to a spiffs file until \ anmarker is encountered, then close file : RECORDFILE ( "filename" "filecontents" "" -- ) bl parse \ read the filename ( a n ) W/O CREATE-FILE throw >R \ create the file to record to - \ put file id on R stack BEGIN \ read a line of the file from the input stream tib #tib accept tib over S" <EOF>" startswith? \ does the line start with <EOF> ? DUP IF \ Yes, so drop the end line of the file containing <EOF> swap drop ELSE swap tib swap \ No, so write the line to the open file R@ WRITE-FILE throw \ and terminate line with cr-lf crlf 2 R@ WRITE-FILE throw THEN UNTIL \ repeat until <EOF> found R> CLOSE-FILE throw \ Close the file ; <EOF>
Copiez à nouveau ce code source, en incluant les lignes de code en rouge. Collez à nouveau ce code dans la fenêtre du terminal. Transmettez ce code à la carte ESP32.
A la différence de la première manipulation qui consiste à compiler le code, cette fois-ci ce code est enregistré dans le fichier /sipffs/autoexec.fs.
Pour vérifier que le fichier autoexec.fs est bien enregistré, exécutez ls :
ls /spiffs/
Normalement, le fichier autoexec.fs doit apparaître dans la liste des fichiers. Pour vérifier le contenu de autoexec.fs, tapez :
cat /spiffs/autoexec.fs
Ceci doit afficher le contenu de autoexec.fs.
Utiliser le contenu modifié du fichier autoexec.fs.
Relancez ESP32forth. Si tout s’est bien passé, RECORDFILE est maintenant
disponible au démarrage de ESP32forth. Exécutez words. Vous devez
retrouver RECORDFILE dans les premiers mots du dictionnaire Forth :
RECORDFILE crlf FORTH spi oled telnetd registers webui login web-interface httpd ok LED OUTPUT INPUT HIGH LOW tone freq duty adc pin default-key? default-key default-type visual set-title page at-xy normal bg fg ansi….
N’encombrez pas autoexec.fs avec d’autres définitions. Nous allons voir comment créer un projet.
Découpage d’un projet avec ESP32forth
Un projet de développement Forth pour ESP32forth est élaboré sur votre PC :
- édition du code source avec l’éditeur texte de votre choix ou un IDE (Netbeans par exemple) ;
- avoir un terminal lié par USB à la carte ESP32 ;
- avoir ESP32forth activé sur la carte ESP32.
Sur le PC, travaillez de manière structurée. Les explications qui suivent ne sont que des préconisations.
Commencez par définir le répertoire général de travail pour tous les développements ESP32forth. Par exemple, un dossier nommé ESP32forth developments.
Ensuite, dans ce dossier, créer deux dossiers annexes :
- _my Projects qui est destiné à accueillir tous vos projets ;
- _sandbox qui est destiné à recevoir tous les petits programmes à tester et n’ayant pas d’utilisation précise ;
- Tools qui est destiné à accueillir tous les fichiers source ayant un intérêt général. Ce sont des fichiers testés et ne requérant pas d’adaptation ;
- Documentation qui est destiné aux documents de toute nature.
Exemple de projet
Je vais reprendre comme exemple de projet le code source de TEMPVS FVGIT. Les codes sources complets sont disponibles ici :
Le premier fichier à créer s’appelle main.fs. Ce fichier est à écrire dans un dossier TEMPVS FVGIT :
ESP32forth developments
+-------------> _my Projects
+-------------> TEMPVS FVGIT
+-------------> main.fs
config.fs
strings.fs
Encore une fois, ceci ne sont que des préconisations. L’intérêt principal est de regrouper tous les composants d’un seul projet. Contenu du fichier main.fs :
RECORDFILE /spiffs/main.fs
DEFINED? --tempusFugit [if] forget --tempusFugit [then]
create --tempusFugit
s" /spiffs/strings.fs" included
s" /spiffs/RTClock.fs" included
s" /spiffs/clepsydra.fs" included
s" /spiffs/config.fs" included
s" /spiffs/oledTools.fs" included
( part of code removed here )
<EOF>
On retrouve notre mot RECORDFILE. Pour enregistrer le code de main.fs
dans le système de fichiers SPIFFS sur la carte ESP32, il suffit de copier ce code source et
de le transmettre à ESP32forth avec le programme terminal.
Dans le code ci-avant, le contenu de main.fs fait un appel au fichier strings.fs. Le code source de ce fichier vient du dossier Tools. C’est une copie de strings.fs qui est ensuite modifié ainsi :
RECORDFILE /spiffs/strings.fs
structures
struct __STRING
ptr field >maxLength \ point to max length of string
ptr field >realLength \ real length of string
ptr field >strContent \ string content
forth
( ... removed part of file )
\ work only with strings. Don't use with other arrays
: input$ { addr len -- }
addr len maxlen$ nip accept
addr __STRING - cell+ >realLength !
;
<EOF>
La copie et la transmission de ce code source crée le fichier strings.fs dans le système de fichiers SPIFFS sur la carte ESP32.
A ce stade, on commence à avoir plusieurs fichiers sur la carte ESP32. Pour compiler l’ensemble des fichiers transférés, on exécutera simplement :
include /spiffs/main.fs
Il n’y a pas de limite aux fichiers pouvant être enregistrés sur la carte ESP32, hormis une limite d’espace physique. L’espace disponible dans le système de fichiers SPIFFS dépasse 1Mo d’espace d’enregistrement.
Si vous êtes amené à modifier le contenu d’un composant logiciel d’usage général, faites-le toujours sur une copie du fichier source de ce composant. Pensez à versionner et dater ces modifications.
Pour chacun des fichiers de ce projet, on intègre RECORDFILE et son terminateur <EOF>.
Dans chaque projet, on retrouve les fichiers main.fs et config.fs. Mais leur contenu est adapté à chaque projet. Pour un projet spécifique, tous les fichiers d’extension fs sont chargés sur la carte ESP32 dans le système de fichiers SPIFFS. La compilation de leur contenu est incroyablement rapide. Mais surtout, le contenu de ces fichiers est préservé entre deux remises en route de la carte ESP32. Au moindre blocage de Forth il est facile de redémarrer la carte et retrouver toutes les définitions de mots du projet sans nécessiter un nouveau transfert par l’intermédiaire du terminal.
La notion de boîte noire
C’est un concept ancien, qui date de l’époque où on développait surtout en assembleur sur des cartes à micro-contrôleur. On le retrouve également avec les classes en programmation objet. Dans le concept de « boîte noire », il faut considérer un sous-programme, une fonction, une méthode comme une boîte noire. On sait ce qu’on y met. On sait ce qui peut en sortir ou comment cette boîte fonctionne, mais on ne s’occupe pas de son fonctionnement interne. On fait confiance à ceux qui ont programmé la « boite noire ».
En langage Forth, un mot a une définition. Quand on passe des paramètres par la pile, au final, seul le concepteur de la définition doit s’assurer du bon fonctionnement de la définition. Et pour s’assurer du bon fonctionnement d’une définition, il est plus que vivement conseillé de ne pas faire des définitions trop longues.
Mon astuce, pour marquer un code vérifié, consiste tout simplement à mettre une ligne de commentaire juste avant la définition. Exemple de code non vérifié :
: fpi* ( fn – fn*pi )
pi f*
;
Le code sera testé en sandbox ou dans un fichier du projet. Peu importe. Une fois testé avec différentes valeurs, je modifie le code source :
\ multiply fn by pi : fpi* ( fn – fn*pi ) pi f* ;
Si on doute de la fiabilité de son code, on peut définir un fichier tests.fs.
Ce fichier est uniquement destiné à réaliser des batteries de tests unitaires. Voir
la définition du mot assert( qui réalise ces tests, définition visible ici :
https://github.com/MPETREMANN11/ESP32forth/blob/main/tools/assert.fs
Et voici un exemple de tests enregistrés dans notre fichier tests.fs :
assert( 0 >gray 0 = ) assert( 1 >gray 1 = ) assert( 2 >gray 3 = ) assert( 3 >gray 2 = ) assert( 4 >gray 6 = ) assert( 5 >gray 7 = ) assert( 6 >gray 5 = ) assert( 7 >gray 4 = )
assert( génère une alerte si le mot testé ne se comporte pas comme prévu.
Pour une définition aussi simple que celle de fpi*, une batterie de tests
peut être nécessaire si on n’a pas fiabilisé le mot f*. On intègre ces tests
dans le fichier main.fs :
RECORDFILE /spiffs/main.fs DEFINED? --tempusFugit [if] forget --tempusFugit [then] create --tempusFugit s" /spiffs/strings.fs" included s" /spiffs/RTClock.fs" included s" /spiffs/clepsydra.fs" included s" /spiffs/config.fs" included s" /spiffs/oledTools.fs" included s" /spiffs/tests.fs" included <EOF>
Évidemment, il faut aussi que le contenu du fichier tests.fs soit transféré sur la carte ESP32.
De cette manière, le cycle complet de compilation intègre également une batterie de tests. Les tests ne garantissent pas que le code soit fiable. Ils permettent seulement de détecter d’éventuels effets de bord si on est amené à modifier des parties de code de l’application.
En résumé, je conseille de fragmenter votre code en intégrant systématiquement ces fichiers :
- main.fs qui est le fichier principal. Avec l’habitude, quelque soit le
nom du projet, vous le compilerez avec une simple exécution de
include /spiffs/main.fs - config.fs qui contient les paramètres de configuration globaux, mots de passe d’un accès WiFi par exemple ;
- tests.fs qui contient une batterie de tests. Si vous ne faites aucun test, la création de ce fichier n’est pas nécessaire.
En suivant ces quelques prescriptions, vous aurez plus de facilité à gérer des applications
complexes. Le gain de temps à chaque compilation des parties de code fiables et
enregistrées dans des fichiers du système de fichiers SPIFFS est le principal argument
pour adopter RECORDFILE.
Legal: site web personnel sans commerce / personal site without seling