Seules les options les plus utiles sont listées ici ; voyez plus bas pour les autres.  

Le préprocesseur C n'est destiné à être utilisé que sur du code source C, C++ ou Objective C. Par le passé, il a été employé abusivement comme un processeur de texte général. Il se cassera les dents sur de l'entrée qui n'obéit pas aux règles lexicales du C. Par exemple, les apostrophes seront interprétées comme le début de constantes caractères, et provoqueront des erreurs. De plus, vous ne pouvez vous compter sur lui pour préserver les caractéristiques de l'entrée qui ne sont pas significatives dans la famille des langages C. Si un Makefile est prétraité, toutes les tabulations « dures » seront supprimées, et le Makefile ne fonctionnera pas.

Cela étant dit, vous pouvez souvent parvenir à utiliser cpp sur des choses qui ne sont pas du C. Les langages de programmation dérivés de l'Algol sont souvent sûrs (Pascal, Ada, etc.). L'assembleur l'est aussi, avec quelques précautions. Le mode -traditional préserve plus de caractères d'espacement, et est dans les autres cas plus permissif. Beaucoup de ces problèmes peuvent être évités en écrivant des commentaires de style C ou C++ au lieu des commentaires du langage natif, et en n'utilisant que des macros simples.

À chaque fois que c'est possible, vous devriez utiliser un préprocesseur adapté au langage dans lequel vous écrivez. Les versions modernes de l'assembleur GNU possèdent des outils de gestion des macros. La plupart des langages de programmation de haut niveau disposent de leurs propres mécanismes de compilation conditionnelle et d'inclusion. En dernier recours, essayez un processeur de texte réellement général, comme GNU M4.

Les préprocesseurs C se différencient en quelques détails. Ce manuel discute du préprocesseur C GNU, qui fournit un petit sur-ensemble des fonctionnalités du C Standard ISO. Dans son mode par défaut, le préprocesseur GNU C ne fait pas quelques actions requises par le standard. Ce sont des fonctionnalités qui sont rarement voire jamais utilisées, et qui peuvent entraîner des modifications surprenantes de la signification d'un programme qui ne s'y attend pas. Pour utiliser le C Standard ISO, vous devriez utiliser les options -std=c89 ou -std=c99, en fonction de la version du standard que vous voulez. Pour obtenir tous les diagnostics obligatoires, vous devez également utiliser -pedantic.  

fichier-entrée ou fichier-sortie peut être -, ce qui pour fichier-entrée signifie de lire à partir de l'entrée standard, et pour fichier-sortie d'écrire sur la sortie standard. De plus, si l'un des fichiers est omis, cela signifie la même chose que si - avait été spécifié pour ce fichier.

À moins que cela ne soit mentionné différemment, ou que l'option se termine par =, toutes les options qui prennent un argument peuvent le voir apparaître immédiatement après l'option, ou avec une espace intermédiaire : -Ifoo et -I foo ont le même effet.

Beaucoup d'options ont un nom composé de plusieurs lettres ; de multiples options composées d'une seule lettre ne peuvent dès lors pas être regroupées : -dM est très différent de -d -M.

-D nom

Prédéfinir nom comme une macro, ayant pour définition 1.

-D nom=définition

Prédéfinir la macro nom, possédant la définition définition. Il n'y a aucune restriction quant au contenu de la définition, mais si vous invoquez le préprocesseur depuis un shell ou un programme de type shell, vous pourriez être dans l'obligation d'utiliser la syntaxe de protection du shell pour protéger les caractères comme les espaces qui y ont une signification spéciale.

Si vous voulez définir une macro du type fonction sur la ligne de commandes, écrivez sa liste d'arguments avec les parenthèses entourantes avant le signe égal (s'il y en a un). Les parenthèses sont significatives dans la plupart des shells, et vous devrez donc protéger l'option. -D'nom(args...)=définition' fonctionne avec sh et csh.

Les options -D et -U sont traitées dans leur ordre d'apparition sur la ligne de commandes. Toutes les options -imacros fichier et -include fichier sont traitées après toutes les options -D et -U.

-U nom

Annuler toute définition précédente de nom, qu'elle soit intégrée ou fournie à l'aide d'une option -D.

-undef

Ne pas prédéfinir de macro spécifique au système. Les macros prédéfinies habituelles restent définies.

-I rép

Ajouter le répertoire rép à la liste des répertoires où chercher les fichiers d'en-tête.

Les répertoires nommés avec -I sont parcourus avant les répertoires d'inclusion système standard.

Il est dangereux de spécifier un répertoire d'inclusion système standard dans une option -I. Cela fait échouer le traitement spécial des en-têtes système. Cela peut également faire échouer les réparations des en-têtes système bogués qu'effectue GCC lors de son installation.

-o fichier

Écrire la sortie dans le fichier. C'est la même chose que de spécifier fichier comme second argument non-option pour cpp. gcc a une interprétation différente du second argument non-option ; vous devez donc utiliser -o pour spécifier le fichier de sortie.

-Wall

Active tous les avertissements optionnels qui sont désirables pour du code normal. Actuellement, il s'agit de -Wcomment et -Wtrigraphs. Notez que beaucoup des avertissements du préprocesseur sont activés par défaut et n'ont pas d'option permettant de les contrôler.

-Wcomment

-Wcomments

Avertir à chaque fois qu'une séquence de début de commentaire /* apparaît dans un commentaire /*, ou quand un backslash suivi d'un saut de ligne apparaît dans un commentaire //. (Les deux formes ont le même effet.)

-Wtrigraphs

Avertir quand des trigraphes sont rencontrés. Cette option n'avait auparavant d'effet que si -trigraphs était également spécifié, mais fonctionne maintenant indépendamment. Des avertissements ne sont pas fournis pour les trigraphes présents à l'intérieur de commentaires, car ils n'affectent pas la signification du programme.

-Wtraditional

Avertir de certaines constructions qui se comportent différemment en C traditionnel et en C ISO. Avertir également des constructions C ISO qui n'ont pas d'équivalent en C traditionnel, et des constructions problématiques qui devraient être évitées.

-Wimport

Avertir la première fois qu'un #import est utilisé.

-Wundef

Avertir quand un identificateur qui n'est pas une macro est rencontré dans une directive #if, en dehors de defined. De tels identificateurs sont remplacés par zéro.

-Werror

Traiter les avertissements comme des erreurs pures et dures. Le code source qui déclenche des avertissements sera rejeté.

-Wsystem-headers

Afficher des messages d'avertissement pour du code des en-têtes système. Ils sont normalement inutiles pour trouver des bogues dans votre propre code, et par conséquent supprimés. Si vous êtes responsable de la bibliothèque système, vous pourriez vouloir les visualiser.

-w

Supprimer tous les avertissements, même ceux que GNU CPP émet par défaut.

-pedantic

Émettre tous les diagnostics obligatoires listés dans le standard C. Certains d'entre eux sont laissés de côté par défaut, car ils se déclenchent fréquemment dans du code inoffensif.

-pedantic-errors

Émettre tous les diagnostics obligatoires, et les traiter comme des erreurs. Cela inclut les diagnostics obligatoires que GCC émet sans -pedantic, mais traite comme des avertissements.

-M

Au lieu de sortir les résultats du prétraitement, générer une règle convenant à make qui décrit les dépendances du fichier source principal. Le préprocesseur génère une règle make contenant le nom du fichier objet pour ce fichier source, un signe deux-points, et le nom de tous les fichiers inclus, y compris ceux provenant des options de ligne de commandes -include ou -imacros.

À moins que cela ne soit spécifié explicitement (avec -MT ou -MQ), le nom du fichier objet est constitué du nom de base du fichier source où le suffixe éventuel est remplacé par le suffixe de fichier objet. S'il y a beaucoup de fichiers inclus, alors la règle est découpée en plusieurs lignes en utilisant \-newline. La règle n'a pas de commande.

Cette option ne supprime pas la sortie de débogage du préprocesseur, comme -dM. Pour éviter de mélanger une telle sortie de débogage avec les règles de dépendances, vous devriez spécifier explicitement le fichier de sortie des dépendances avec -MF, ou utiliser une variable d'environnement comme DEPENDENCIES_OUTPUT. La sortie de débogage sera toujours envoyée dans le flux de sortie normal comme de coutume.

Passer -M au pilote implique -E.

-MM

Comme -M, mais ne pas mentionner les fichiers d'en-tête qui sont trouvés dans les répertoires d'en-tête système, ni les fichiers d'en-tête qui sont inclus, directement ou indirectement, depuis un tel en-tête.

Cela implique que le choix de crochets pointus (< et >) ou de guillemets dans une directive #include ne détermine pas en lui-même si l'en-tête apparaîtra dans la sortie de dépendances de -MM. C'est un léger changement dans la sémantique depuis les versions 3.0 et antérieures de GCC.

-MF fichier

@anchor{-MF} Quand utilisé avec -M ou -MM, spécifie un fichier où écrire les dépendances. Si aucun interrupteur -MF n'est fourni, le préprocesseur envoie les règles au même endroit où il aurait envoyé la sortie prétraitée.

Quand il est utilisé avec les options du pilote -MD ou -MMD, -MF surcharge le fichier de sortie des dépendances par défaut.

-MG

Quand utilisé avec -M ou -MM, -MG dit de traiter les fichiers d'en-tête manquants comme des fichiers générés et supposer qu'ils résident dans le même répertoire que le fichier source. Cela supprime la sortie prétraitée, car un fichier d'en-tête manquant constitue généralement une erreur.

Cette fonctionnalité est utilisée lors de la mise à jour automatique de makefiles.

-MP

Cette option indique à CPP d'ajouter une cible « phony » pour chaque dépendance autre que le fichier principal, ne les faisant dépendre de ce fait de rien du tout. Ces règles factices surmontent des erreurs que vous donne make si vous supprimez des fichiers d'en-tête sans mettre à jour le Makefile pour qu'il concorde.

Voici une sortie typique :

        test.o: test.c test.h

        test.h:

-MT cible

Changer la cible de la règle émise lors de la génération des dépendances. Par défaut, CPP prend le nom du fichier d'entrée principal, chemin inclus, supprime tout suffixe de fichier comme .c, et concatène le suffixe de fichier objet habituel de la plate-forme. Le résultat constitue la cible.

Une option -MT définira la cible pour qu'elle soit exactement la chaîne de caractères que vous spécifiez. Si vous voulez plusieurs cibles, vous pouvez les spécifier comme un unique argument de -MT, ou utiliser plusieurs options -MT.

Par exemple, -MT '$(objpfx)foo.o' pourrait donner

        $(objpfx)foo.o: foo.c

-MQ cible

Comme -MT, mais protège les caractères qui sont spéciaux pour Make. -MQ '$(objpfx)foo.o' donne

        $$(objpfx)foo.o: foo.c

La cible par défaut est automatiquement protégée, comme si elle avait été fournie avec -MQ.

-MD

-MD est équivalent à -M -MF fichier, sauf que -E n'est pas impliqué. Le pilote détermine le fichier en fonction de l'utilisation éventuelle d'une option -o est donnée. Si c'est le cas, le pilote utilise son argument mais avec un suffixe .d ; sinon, il prend le nom de base du fichier d'entrée et lui applique un suffixe .d.

Si -MD est utilisé en conjonction avec -E, tout interrupteur -o est censé spécifier le fichier de sortie des dépendances (sauf @pxref{-MF}), mais s'il est utilisé sans -E, chaque -o est censé spécifier un fichier objet cible.

Puisque -E n'est pas impliqué, -MD peut être utilisé pour générer un fichier de sortie de dépendances comme effet de bord du processus de compilation.

-MMD

Comme -MD, sauf que seuls les fichiers d'en-tête utilisateurs sont mentionnés, et pas les fichiers d'en-tête système.

-x c

-x c++

-x objective-c

-x assembler-with-cpp

Spécifier le langage source : C, C++, Objective-C, ou assembleur. Cela n'a rien à voir avec la conformité aux standards ou avec des extensions ; cela précise simplement à quelle syntaxe de base on doit s'attendre. Si vous ne fournissez aucune de ces options, cpp déduira le langage à partir de l'extension du fichier source : .c, .cc, .m ou .S. Certaines autres extensions habituelles pour le C++ et l'assembleur sont également reconnues. Si cpp ne reconnaît pas l'extension, il traitera le fichier comme étant du C ; c'est le mode le plus générique.

Note : De précédentes versions de cpp acceptaient une option -lang qui sélectionnait à la fois le langage et le niveau de conformité aux standards. Cette option a été supprimée, car elle entre en conflit avec l'option -l.

-std=standard

-ansi

Spécifier le standard auquel le code devrait se conformer. Actuellement, cpp ne connaît que les standards du C ; d'autres standards de langages seront ajoutés dans le futur.

Le standard peut être :

iso9899:1990

c89

Le standard C ISO de 1990. c89 est le raccourci habituel pour cette version du standard.

L'option -ansi est équivalente à -std=c89.

iso9899:199409

Le standard C 1990, comme amendé en 1994.

iso9899:1999

c99

iso9899:199x

c9x

La standard C ISO révisé, publié en décembre 1999. Avant sa publication, il était connu sous le nom C9X.

gnu89

Le standard C 1990 plus les extensions GNU. C'est le standard par défaut.

gnu99

gnu9x

Le standard C 1999 plus les extensions GNU.

-I-

Diviser le chemin d'inclusion. Tout répertoire spécifié avec une option -I avant -I- n'est parcouru que pour les en-têtes requis avec « #include "fichier" » ; il n'est pas parcouru pour des « #include <fichier> ». Si des répertoires additionnels sont spécifiés par des options -I après le -I-, ces répertoires sont parcourus pour chaque directive #include.

De plus, -I- empêche l'utilisation du répertoire courant (où est situé le fichier d'entrée actuel) comme premier répertoire de recherche pour « #include "fichier" ».

-nostdinc

Ne pas chercher les fichiers d'en-tête dans les répertoires standard du système. Seuls les répertoires que vous avez spécifiés avec des options -I (et le répertoire courant, si c'est approprié) sont parcourus.

-nostdinc++

Ne pas rechercher de fichiers d'en-tête dans les répertoires standard spécifiques au C++, mais toujours les chercher dans les autres répertoires standard. (Cette option est utilisée lors de la construction de la bibliothèque C++.)

-include fichier

Traiter fichier comme si « #include "fichier" » était apparu comme première ligne du fichier source principal. Néanmoins, le premier répertoire parcouru pour trouver fichier est le répertoire de travail du préprocesseur plutôt que le répertoire contenant le fichier source principal. S'il n'est pas trouvé là, il est recherché dans le reste de la chaîne de recherche « #include "..." » comme de coutume.

Si plusieurs options -include sont fournies, les fichiers sont inclus dans leur ordre d'apparition sur la ligne de commandes.

-imacros fichier

Exactement comme -include, sauf que toute sortie produite lors de l'analyse du fichier est jetée. Les macros qu'il définit restent définies. Cela vous permet d'obtenir toutes les macros d'un en-tête sans devoir également traiter ses déclarations.

Tous les fichiers spécifiés par -imacros sont traités avant tous les fichiers spécifiés par -include.

-idirafter répertoire

Rechercher des fichiers d'en-tête dans le répertoire, mais après que les répertoires spécifiés par -I et les répertoires système standard aient été épuisés. répertoire est traité comme un répertoire d'inclusion système.

-iprefix préfixe

Spécifier le préfixe des options -iwithprefix ultérieures. Si le préfixe représente un répertoire, vous devriez inclure le / final.

-iwithprefix répertoire

-iwithprefixbefore répertoire

Concaténer répertoire au préfixe spécifié précédemment avec -iprefix, et ajouter le répertoire résultant au chemin de recherche d'inclusion. -iwithprefixbefore le place au même endroit que le ferait -I ; -iwithprefix le place au même endroit que -idirafter.

L'utilisation de ces options est découragée.

-isystem répertoire

Rechercher des fichiers d'en-tête dans le répertoire, après tous les répertoires spécifiés par -I, mais avant les répertoires système standard. Le marquer comme étant un répertoire système, afin qu'il ait droit au même traitement spécial que celui qui s'applique aux répertoires système standard.

-fpreprocessed

Indiquer au préprocesseur que le fichier d'entrée a déjà été prétraité. Cela supprime certaines choses comme l'expansion des macros, la conversion des trigraphes, le découpage de sauts de ligne protégés (escaped newline splicing), et le traitement de la plupart des directives. Le préprocesseur reconnaît et supprime toujours les commentaires, afin que vous puissiez passer au compilateur un fichier prétraité avec -C sans conséquence fâcheuse. Dans ce mode, le préprocesseur intégré est un peu plus qu'un analyseur lexical pour les frontaux.

-fpreprocessed est implicite si le fichier d'entrée possède l'une des extensions .i, .ii ou .mi. Ce sont les extensions que GCC utilise pour les fichiers prétraités créés par -save-temps.

-ftabstop=largeur

Fixer la distance entre les taquets de tabulation. Cela aide le préprocesseur à rapporter des numéros de colonnes corrects dans les avertissements ou erreurs, même si des tabulations apparaissent sur la ligne. Si la valeur est plus petite que 1 ou plus grande que 100, l'option est ignorée. La distance par défaut est 8.

-fno-show-column

Ne pas afficher les numéros des colonnes dans les diagnostics. Cela peut être nécessaire si les diagnostics sont exploités par un programme qui ne comprend pas les numéros de colonnes, comme dejagnu.

-A prédicat=réponse

Faire une assertion de prédicat prédicat et de réponse réponse. Cette forme est préférée à la forme plus ancienne -A prédicat(réponse), qui est toujours supportée, car n'utilisant pas les caractères spéciaux du shell.

-A -prédicat=réponse

Annuler une assertion de prédicat prédicat et de réponse réponse.

-A-

Annuler toutes les assertions prédéfinies et toutes les assertions précédant cette option sur la ligne de commandes. Supprimer également la définition de toutes les macros prédéfinies et de toutes les macros préalablement spécifiées sur la ligne de commandes. (C'est une excroissance historique et cela pourrait changer dans le futur.)

-dCARS

CARS est une séquence constituée d'un ou de plusieurs des caractères suivants, non précédés d'une espace. D'autres caractères sont interprétés par le compilateur lui-même, ou réservés pour des versions futures de GCC, et sont par conséquent ignorés silencieusement. Si vous spécifiez des caractères dont les comportements ne sont pas compatibles, le résultat est indéfini.

M

Au lieu de la sortie normale, générer une liste de directives #define pour toutes les macros définies durant l'exécution du préprocesseur, macros prédéfinies comprises. Cela vous donne un moyen de découvrir ce qui est prédéfini dans votre version du préprocesseur. En supposant que vous n'avez pas de fichier foo.h, la commande

        touch foo.h; cpp -dM foo.h

affichera toutes les macros prédéfinies.

D

Comme M sauf en deux endroits : il n'inclut pas les macros prédéfinies, et il sort à la fois les directives #define et le résultat du prétraitement. Les deux types de sortie vont dans le fichier de sortie standard.

N

Comme D, mais n'émet que le nom des macros, et pas leur développement.

I

Produire des directives #include en plus du résultat du prétraitement.

-P

Empêcher la génération de marqueurs de ligne dans la sortie du préprocesseur. Cela pourrait être utile quand on exécute le préprocesseur sur quelque chose qui n'est pas du code C, et qui sera envoyé à un programme qui pourrait être embrouillé à cause des marqueurs de ligne.

-C

Ne pas éliminer les commentaires. Tous les commentaires sont passés dans le fichier de sortie, sauf ceux présents dans les directives traitées, qui sont effacés en même temps que la directive.

Vous devriez vous attendre à des effets de bord quand vous utilisez -C ; cette option force le préprocesseur à traiter les commentaires comme des éléments lexicaux à part entière. Par exemple, les commentaires apparaissant au début de ce qui serait une ligne de directive ont pour effet de transformer cette ligne en une ligne de code source ordinaire, puisque le premier élément lexical de la ligne n'est plus un #.

-gcc

Définir les macros __GNUC__, __GNUC_MINOR__ et __GNUC_PATCHLEVEL__. Elles sont définies automatiquement quand vous utilisez gcc -E ; vous pouvez les désactiver dans ce cas avec -no-gcc.

-traditional

Essayer d'imiter le comportement du C à l'ancienne, en opposition avec le C ISO.

-trigraphs

Prendre en charge les séquences de trigraphes.

-remap

Activer du code spécial pour s'accommoder de systèmes de fichiers qui ne permettent que des noms de fichiers très courts, comme MS-DOS.

-$

Interdire l'utilisation du $ dans les identificateurs. Le standard C autorise les implémentations à définir des caractères supplémentaires pouvant apparaître dans les identificateurs. Par défaut, GNU CPP autorise le $, une extension habituelle.

-h

--help

--target-help

Afficher du texte décrivant toutes les options de ligne de commandes au lieu de prétraiter quoi que ce soit.

-v

Mode verbeux. Afficher le numéro de version de GNU CPP au début de l'exécution, et rapporter la forme finale du chemin d'inclusion.

-H

Afficher le nom de chaque fichier d'en-tête utilisé, en plus d'autres activités normales. Chaque nom est indenté pour montrer sa profondeur dans la pile de #include.

-version

--version

Afficher le numéro de version de GNU CPP. Avec un tiret, continuer le prétraitement comme de coutume. Avec deux tirets, s'arrêter immédiatement.

Notez que vous pouvez également spécifier des endroits où chercher en utilisant des options comme -I, et contrôler la sortie des dépendances avec des options comme -M. Elles sont prioritaires sur les variables d'environnement, qui sont à leur tour prioritaires sur la configuration de GCC.

CPATH

C_INCLUDE_PATH

CPLUS_INCLUDE_PATH

OBJC_INCLUDE_PATH

La valeur de chaque variable est une liste de répertoires séparés par un caractère spécial, un peu comme PATH, dans lesquels on cherche les fichiers d'en-tête. Le caractère spécial, « PATH_SEPARATOR », dépend de la cible et est déterminé au moment de la construction de GCC. Pour les cibles basées sur Windows, c'est un point-virgule, et pour pratiquement toutes les autres cibles, c'est un signe deux-points.

CPATH spécifie une liste de répertoires à parcourir comme s'ils avaient été spécifiés par -I, mais après tous les chemins fournis par des options -I sur la ligne de commandes. La variable d'environnement est utilisée quel que soit le langage en cours de prétraitement.

Les variables d'environnement restantes ne s'appliquent que lors du prétraitement du langage particulier indiqué. Chacune d'entre elles spécifie une liste de répertoires à parcourir comme s'ils avaient été spécifiés par -isystem, mais après tous les chemins fournis par des options -isystem sur la ligne de commandes.

Voyez aussi @ref{Search Path}.

DEPENDENCIES_OUTPUT

@anchor{DEPENDENCIES_OUTPUT} Si cette variable est définie, sa valeur spécifie la façon de produire des dépendances pour Make basées sur les fichiers d'en-tête non-système traités par le compilateur. Les fichiers d'en-tête système sont ignorés dans la sortie des dépendances.

La valeur de DEPENDENCIES_OUTPUT peut être simplement un nom de fichier, auquel cas les règles Make sont écrites dans ce fichier, en devinant le nom de la cible à partir du nom de fichier source, ou bien la valeur peut avoir la forme fichier cible, auquel cas les règles sont écrites dans le fichier en utilisant cible comme nom de cible.

En d'autres termes, cette variable d'environnement est équivalente à la combinaison des options -MM et -MF, complétée par un interrupteur -MT éventuel.

SUNPRO_DEPENDENCIES

Cette variable est identique à la variable d'environnement DEPENDENCIES_OUTPUT, mis à part que les fichiers d'en-tête système ne sont pas ignorés, et implique donc -M plutôt que -MM. Néanmoins, les dépendances du fichier d'entrée principal sont omises.

L'autorisation est donnée de copier, de distribuer et/ou de modifier ce document sous les termes de la GNU Free Documentation License version 1.1 ou toute autre version ultérieure publiée par la Free Software Foundation. Une copie de la licence est incluse dans la page de manuel gfdl(7). Ce manuel ne contient aucune section invariante. Le texte de couverture est (a) (voir ci-dessous), et le texte de quatrième de couverture est (b) (voir ci-dessous).

(a) Le texte de couverture de la FSF est :

     Un Manuel GNU

(b) Le texte de quatrième de couverture de la FSF est :

     Vous êtes libre de copier et de modifier ce manuel GNU,
     tout comme les logiciels GNU. Les copies publiées par la Free
     Software Foundation collectent des fonds pour le
     développement de GNU.

NOM

SYNOPSIS

DESCRIPTION

OPTIONS

ENVIRONNEMENT

VOIR AUSSI

COPYRIGHT

TRADUCTION