/external (Diagnostics d’en-têtes externes)

Les /external options du compilateur vous permettent de spécifier le comportement de diagnostic du compilateur pour certains fichiers d’en-tête. Les en-têtes « Externes » sont le complément naturel de « Juste mon code » : les fichiers d’en-tête tels que les fichiers système ou les fichiers de bibliothèque tiers que vous ne pouvez pas ou n’ont pas l’intention de modifier. Étant donné que vous n’allez pas modifier ces fichiers, vous pouvez décider qu’il n’est pas utile de voir les messages de diagnostic du compilateur à leur sujet. Les options du /external compilateur vous permettent de contrôler ces avertissements.

Les /external options du compilateur sont disponibles à partir de Visual Studio 2017 version 15.6. Dans les versions de Visual Studio avant Visual Studio 2019 version 16.10, les /external options nécessitent également de définir l’option du /experimental:external compilateur.

Syntaxe

Utilisez les options d’en-tête externe (non requises dans la version 16.10 et ultérieures) :

/experimental:external

Spécifiez des en-têtes externes :

/external:anglebrackets
/external:env:var
/external:I path

Spécifiez le comportement des diagnostics :

/external:W0
/external:W1
/external:W2
/external:W3
/external:W4
/external:templates-

Arguments

/experimental:external
Active les options d’en-têtes externes. Cette option n’est pas obligatoire dans Visual Studio 2019 version 16.10 et versions ultérieures.

/external:anglebrackets
Traite tous les en-têtes inclus par #include <header>, où le header fichier est placé entre crochets d’angle (< >), en tant qu’en-têtes externes.

/external:I path
Définit un répertoire racine qui contient des en-têtes externes. Tous les sous-répertoires récursifs sont path considérés comme externes, mais seule la path valeur est ajoutée à la liste des répertoires que le compilateur recherche pour inclure des fichiers. L’espace entre /external:I et path est facultatif. Les répertoires qui incluent des espaces doivent être placés entre guillemets doubles. Un répertoire peut être un chemin absolu ou un chemin relatif.

/external:env:var
Spécifie le nom d’une variable var d’environnement qui contient une liste séparée par des points-virgules des répertoires d’en-tête externes. Il est utile pour les systèmes de génération qui s’appuient sur des variables d’environnement telles que INCLUDE, que vous utilisez pour spécifier la liste des fichiers include externes. Ou, CAExcludePathpour les fichiers qui ne doivent pas être analysés par /analyze. Par exemple, vous pouvez spécifier de créer /external:env:INCLUDE chaque répertoire dans INCLUDE un répertoire d’en-tête externe à la fois. Il est identique à l’utilisation /external:I pour spécifier les répertoires individuels, mais beaucoup moins détaillé. Il ne doit pas y avoir d’espace entre var et /external:env:.

/external:Wn
Cette option définit le niveau n d’avertissement par défaut sur (une valeur comprise entre 0 et 4) pour les en-têtes externes. Par exemple, /external:W0 désactive efficacement les avertissements pour les en-têtes externes. Si cette option n’est pas spécifiée, le compilateur émet l’avertissement de ligne de commande D9007 pour d’autres /external options. Ces options sont ignorées, car elles n’auraient aucun effet.

L’option /external:Wn a un effet similaire à l’en-tête inclus dans une #pragma warning directive :

#pragma warning (push, 0)
// the global warning level is now 0 here
#include <external_header>
#pragma warning (pop)

/external:templates-
Autorise les avertissements des en-têtes externes lorsqu’ils se produisent dans un modèle instancié dans votre code.

Notes

Par défaut, le /Wn niveau d’avertissement que vous spécifiez pour votre build s’applique à tous les fichiers. Les options permettant de spécifier des en-têtes externes définissent uniquement un ensemble de fichiers auxquels vous pouvez appliquer un autre niveau d’avertissement par défaut. Par conséquent, si vous spécifiez des en-têtes externes, utilisez /external:Wn également pour spécifier un niveau d’avertissement externe pour modifier le comportement du compilateur.

Tous les mécanismes existants permettant d’activer, de désactiver et de supprimer les avertissements fonctionnent toujours dans des fichiers externes et non externes. Par exemple, un warning pragma peut toujours remplacer le niveau d’avertissement par défaut que vous avez défini pour les en-têtes externes.

Exemple : Définir le niveau d’avertissement externe

Cet exemple de programme a deux fichiers sources et program.cppheader_file.h. Le header_file.h fichier se trouve dans un include_dir sous-répertoire du répertoire contenant le program.cpp fichier :

Fichier source include_dir/header_file.h :

// External header: include_dir/header_file.h

template <typename T>
struct sample_struct
{
    static const T value = -7; // W4: warning C4245: 'initializing':
    // conversion from 'int' to 'unsigned int', signed/unsigned mismatch
};

Fichier source program.cpp :

// User code: program.cpp
#include <header_file.h>

int main()
{
    return sample_struct<unsigned int>().value;
}

Vous pouvez générer l’exemple à l’aide de cette ligne de commande :

cl /EHsc /I include_dir /W4 program.cpp

Comme prévu, cet exemple génère un avertissement :

program.cpp
include_dir\header_file.h(6): warning C4245: 'initializing': conversion from 'int' to 'const T', signed/unsigned mismatch
        with
        [
            T=unsigned int
        ]
program.cpp(6): note: see reference to class template instantiation 'sample_struct<unsigned int>' being compiled

Pour traiter le fichier d’en-tête comme un fichier externe et supprimer l’avertissement, vous pouvez utiliser cette ligne de commande à la place* :

cl /EHsc /I include_dir /external:anglebrackets /external:W0 /W4 program.cpp

Cette ligne de commande supprime l’avertissement à l’intérieur header_file.h tout en préservant les avertissements à l’intérieur program.cpp.

Avertissements sur la limite interne et externe

La définition d’un niveau d’avertissement faible pour les en-têtes externes peut masquer certains avertissements actionnables. En particulier, il peut désactiver les avertissements émis sur les instanciations de modèle dans le code utilisateur. Ces avertissements peuvent indiquer un problème dans votre code qui se produit uniquement dans les instanciations pour des types particuliers. (Par exemple, si vous avez oublié d’appliquer une caractéristique de type en supprimant const ou &.) Pour éviter les avertissements de filtrage dans les modèles définis dans les en-têtes externes, vous pouvez utiliser l’option /external:templates- . Le compilateur considère à la fois le niveau d’avertissement effectif dans le fichier qui définit le modèle et le niveau d’avertissement où l’instanciation du modèle se produit. Les avertissements émis à l’intérieur d’un modèle externe s’affichent si le modèle est instancié dans du code non externe. Par exemple, cette ligne de commande réactive les avertissements des sources de modèle dans l’exemple de code* :

cl /EHsc /I include_dir /external:anglebrackets /external:W0 /external:templates- /W4 program.cpp

L’avertissement C4245 apparaît à nouveau dans la sortie, même si le code du modèle se trouve à l’intérieur d’un en-tête externe.

Activer, désactiver ou supprimer des avertissements

Tous les mécanismes existants pour activer, désactiver et supprimer les avertissements fonctionnent toujours dans les en-têtes externes. Lorsqu’un avertissement s’affiche parce que vous utilisez l’option /external:templates- , vous pouvez toujours supprimer l’avertissement au point d’instanciation. Par exemple, pour supprimer explicitement l’avertissement dans l’exemple qui réapparaît en raison de /external:templates-, utilisez une warning directive pragma :

int main()
{
    #pragma warning( suppress : 4245)
    return sample_struct<unsigned int>().value;
}

Les enregistreurs de bibliothèque peuvent utiliser les mêmes mécanismes pour appliquer certains avertissements, ou tous les avertissements à un certain niveau, s’ils estiment que ces avertissements ne doivent jamais être silencieux par /external:Wn. Par exemple, cette version du fichier d’en-tête force l’avertissement C4245 à signaler une erreur :

// External header: include_dir/header_file.h

#pragma warning( push, 4 )
#pragma warning( error : 4245 )

template <typename T>
struct sample_struct
{
    static const T value = -7; // W4: warning C4245: 'initializing': conversion from 'int'
                               // to 'unsigned int', signed/unsigned mismatch
};

#pragma warning( pop )

Avec cette modification de l’en-tête de la bibliothèque, l’auteur de la bibliothèque garantit que le niveau d’avertissement global dans cet en-tête est 4, quelle que soit la valeur spécifiée dans /external:Wn. À présent, tous les avertissements de niveau 4 et versions ultérieures sont signalés. L’auteur de la bibliothèque peut également forcer certains avertissements à être des erreurs, désactivés, supprimés ou émis une seule fois dans l’en-tête. Les /external options ne remplacent pas ce choix délibéré.

system_header pragma

#pragma system_header est un marqueur intrusif qui permet aux enregistreurs de bibliothèque de marquer certains en-têtes comme externes. Un fichier contenant #pragma system_header est considéré comme externe du point du pragma à la fin du fichier, comme s’il était spécifié comme externe sur la ligne de commande. Le compilateur émet tous les diagnostics après le pragma au niveau d’avertissement spécifié par /external:Wn. Pour plus d’informations, consultez system_header pragma.

Limites

Certains avertissements émis par la génération de code principal du compilateur ne sont pas affectés par les /external options. Ces avertissements commencent généralement par C47XX, mais tous les avertissements C47XX ne sont pas tous des avertissements back-end. Vous pouvez toujours désactiver ces avertissements individuellement à l’aide /wd47XXde . Les avertissements d’analyse du code ne sont pas affectés, car ils n’ont pas de niveaux d’avertissement.

Pour définir cette option du compilateur dans l'environnement de développement Visual Studio

Dans Visual Studio 2019 version 16.10 et ultérieures :

1. Ouvrez la boîte de dialogue Pages de propriété du projet. Pour plus d’informations, consultez Définir le compilateur C++ et les propriétés de build dans Visual Studio.

2. Sélectionnez la page de propriétés des répertoires VC++ Propriétés>de configuration.

3. Définissez la propriété Répertoires Include externes pour spécifier l’ÉQUIVALENT IDE de l’option /external:I path pour chaque chemin délimité par des points-virgules.

4. Sélectionnez la page de propriétés C/C++External Includes des propriétés des propriétés>C/C++.>

5. Définissez les propriétés :

   • Définissez Traiter les fichiers inclus avec des crochets angle comme externes sur Oui pour définir l’option /external:anglebrackets .

   • Le niveau d’avertissement d’en-tête externe vous permet de définir l’option /external:Wn . Si cette valeur est définie sur Hériter du niveau d’avertissement du projet ou par défaut, d’autres /external options sont ignorées.

   • Définissez Les diagnostics de modèle dans les en-têtes externes sur Oui pour définir l’option /external:templates- .

6. Choisissez OK ou Appliquer pour enregistrer vos modifications.

Dans les versions de Visual Studio avant Visual Studio 2019 version 16.10 :

1. Ouvrez la boîte de dialogue Pages de propriété du projet. Pour plus d’informations, consultez Définir le compilateur C++ et les propriétés de build dans Visual Studio.

2. Sélectionnez la page de propriétés Propriétés de configuration>C/C++>Ligne de commande.

3. Entrez l’option /experimental:external et d’autres /external options du compilateur dans la zone Options supplémentaires.

4. Choisissez OK ou Appliquer pour enregistrer vos modifications.

Pour définir cette option du compilateur par programmation

• Consultez AdditionalOptions.

* Ajoutez l’option /experimental:external permettant d’activer les options d’en-têtes externes dans les versions de Visual Studio avant Visual Studio 2019 version 16.10.

Voir aussi

Options du compilateur MSVC
Syntaxe de ligne de commande du compilateur MSVC