commit cfa5c75f45aeed1adafe603d4a24243c55a8ef61
parent 35f45e7b39e88d13f5f2628c11ad13591b837bce
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Thu, 25 Jun 2026 18:40:08 +0200
Ajoute la section sur la visibilité des symboles
Diffstat:
| M | doc/fr/star-c.7 | | | 159 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1 file changed, 159 insertions(+), 0 deletions(-)
diff --git a/doc/fr/star-c.7 b/doc/fr/star-c.7
@@ -478,6 +478,164 @@ reduire les temps de compilation.
.Pp
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh LA VISIBILITÉ DES SYMBOLES
+Par défaut, n'exposer aucun symbole
+.Po
+option
+.Fl -fvisibility=hidden
+du compilateur
+.Xr gcc 1
+.Pc ,
+à l exception de ceux de l'interface de programmation d'une
+bibliothèque.
+.\""""""""""""""""""""""""""""""""""
+.Ss Les symboles d'interface
+Privilégier l'écriture d'un seul fichier d'en-tête pour exposer
+l'interface de programmation d'une bibliothèque.
+Y définir une macro d'API qui exporte les symboles qu'elle déclare dès
+lors que ce fichier d'en-tête est inclus par une unité de compilation de
+la bibliothèque.
+Et qui se contente d'importer ces mêmes symboles si ce même fichier est
+inclus par un programme tiers :
+.Bd -literal -offset Ds
+#include <rsys/rsys.h>
+
+#if defined(FOO_SHARED_BUILD)
+ #define FOO_API extern EXPORT_SYM
+else
+ #define FOO_API extern IMPORT_SYM
+#endif
+.Ed
+.Pp
+Avec :
+.Bl -dash -compact
+.It
+.Sy FOO_SHARED_BUILD
+une macro définie uniquement à la compilation de la bibliothèque
+.Po
+option
+.Fl -D FOO_SHARED_BUILD
+du compilateur C
+.Pc Ns
+ ;
+.It
+.Sy EXPORT_SYM
+et
+.Sy IMPORT_SYM
+des macros de la bibliothèque RSys.
+Elles enrichissent le langage C d'une gestion explicite de la visibilité
+des symboles.
+.El
+.Pp
+.Bd -literal -offset Ds
+/* Variables globales de l'interface de programmation */
+FOO_API const struct foo foo_plugh;
+FOO_API const struct foo foo_xyzzy;
+.Ed
+.Pp
+Déclarer le prototype des fonctions d'interface entre les directives
+.Sy BEGIN_DECLS
+et
+.Sy END_DECLS ,
+elles aussi définies dans la bibliothèque RSys
+.Pq en-tête In rsys/rsys.h .
+Ainsi, le fichier d'en-tête peut être inclus par un programe C++ :
+.Bd -literal -offset Ds
+BEGIN_DECLS
+
+FOO_API void
+foo_bar
+ (int i,
+ int* j);
+
+FOO_API int
+foo_qux
+ (double d,
+ int i);
+
+END_DECLS
+.Ed
+.\""""""""""""""""""""""""""""""""""
+.Ss Les symboles internes partagés
+Pour les fichiers d'en-tête internes au programme utiliser la directive
+.Sy LOCAL_SYM ,
+défini dans le fichier
+.In rsys/rsys.h
+de la bibliothèque RSys, pour déclarer les variables globales et
+prototypes de fonctions.
+Ainsi leur symbole n'est pas exposé à l'extérieur du programme.
+.Bd -literal -offset Ds
+#include <rsys/rsys.h>
+
+extern LOCAL_SYM char bar[128];
+
+extern LOCAL_SYM void
+quux
+ (char* tab,
+ size_t length);
+.Ed
+.Pp
+Cette directive est redondante si le compilateur est configuré pour
+masquer par défaut tous les symboles
+.Po
+option
+.Fl -fvisibility=hidden
+de
+.Xr gcc 1
+.Pc .
+Utiliser
+.Sy LOCAL_SYM
+permet néanmoins de s'exonérer de cet a priori, tout en uniformisant
+les déclaration des fonctions et variables où, pour chacune d'elles, la
+visibilité du symbole associé est alors explicite.
+.\""""""""""""""""""""""""""""""""""
+.Ss Les symboles internes à une unité de compilation
+Utiliser le mot clé
+.Sy static
+pour déclarer des variables et fonctions visibles uniquement au sein
+d'une unité de compilation.
+.Pp
+C'est le cas notamment des constantes globales :
+.Bd -literal -offset Ds
+struct foo {
+ int bar;
+ int qux;
+};
+static const struct foo FOO_DEFAULT = {1, 0};
+.Ed
+.Pp
+Mais aussi des fonctions utilitaires, qu'elles soient
+propres à un fichier C, ou définies dans un fichier d'en-tête.
+.Bd -literal -offset Ds
+static void
+hello(void)
+{
+ printf("Hello, world!\en");
+}
+.Ed
+.Pp
+Ces fonctions peuvent en plus être déclarées avec la directive
+.Sy INLINE ,
+définie dans l'en-tête
+.In rsys/rsys.h
+de la bibliothèque RSys,
+pour suggérer au compilateur de substituer l'appel de la fonction par le
+corps de la fonction elle-même, de sorte à éviter le surcoût de l'appel.
+Cette directive est équivalente au mot clé
+.Sy inline
+du C99, indisponible dans le dialecte C retenu
+.Pq section Sx LE LANGAGE C .
+.Bd -literal -offset Ds
+static INLINE void
+foo(void)
+{
+ printf("bar\en");
+}
+.Ed
+.Pp
+Limiter la directive INLINE aux fonctions élémentaires, destinées à être
+appelées fréquemment et dont le coût de l'appel pourrait alors s'avérer
+significatif.
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh LES BLOCS
.Sh LES MOTS CLÉS
.Sh LE NOMMAGE
@@ -493,6 +651,7 @@ reduire les temps de compilation.
.Sh FICHIERS
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh VOIR AUSSI
+.Xr gcc 1
.Xr feature_test_macros 7
.Pp
.Rs
