title	/headerName (Build a header unit from the specified header)
description	Use the /headerName compiler option to establish a mapping between a header file and the header unit to build.
ms.date	04/13/2021
author	tylermsft
ms.author	twhitney
f1_keywords	/headerName
helpviewer_keywords	/headerName Use header unit IFC

/headerName (Build a header unit from the specified header)

Build the specified header file into a header unit (.ifc file).

Syntax

/headerName:quote header-filename
/headerName:angle header-filename

Arguments

header-filename
The name of a header file that the compiler should compile into a header unit (.ifc file).

Remarks

The /headerName compiler option is available starting in Visual Studio 2019 version 16.10.

The /headerName compiler option, in all its forms, requires the /std:c++20 or later compiler option (such as /std:c++latest).
If you specify /headerName:{quote,angle}, you must also specify /exportHeader.

/headerName:quote looks up header-filename using the same rules as #include "header-name" and builds it as a header unit (.ifc file).
/headerName:angle looks up header-filename using the same rules as #include <header-name> and builds it as a header unit (.ifc file).

Examples

Given a project that references a header file it defines called m.h, the compiler option to compile it into a header unit looks similar to this:

cl /std:c++latest /exportHeader /headerName:quote m.h /Fom.h.obj

The /headerName:{quote,angle} option acts like a flag and does not explicitly need an argument. The following examples are valid:

cl /std:c++latest /exportHeader /headerName:angle /MP /Fo.\ vector iostream algorithm
cl /std:c++latest /exportHeader /headerName:quote /MP /Fo.\ my-utilities.h a/b/my-core.h

You can specify multiple /headerName options on the same command line, and every argument after that option will be processed with the specified header-filename lookup rules. The following example processes all the headers as the previous two command line examples in the same way. It looks up the headers using the lookup rules applied as if they had been specified as: #include <vector>, #include "my-utilties.h", and #include "a/b/my-core.h":

cl /std:c++latest /exportHeader /headerName:angle /MP /Fo.\ vector iostream algorithm /headerName:quote my-utilities.h a/b/my-core.h

To set this compiler option in the Visual Studio development environment

Note

Users don't typically set this command line option. It's set by the build system.

1. Open the project's Property Pages dialog box. For details, see Set C++ compiler and build properties in Visual Studio.

2. Set the Configuration drop-down to All Configurations.

3. Select the Configuration Properties > C/C++ > Command Line property page.

4. Modify the Additional Options property to add the /headerName options and arguments. Then, choose OK or Apply to save your changes.

See also

/exportHeader (Create header units)
/headerUnit (Create header units)
/reference (Use named module IFC)
/translateInclude (Translate include directives into import directives)