How do I use Header Units with the Windows Desktop Application default template and resolve conflicts with headers?

CDev-8220 220

I am trying to use Header Units in a Desktop Application, but am getting problems with headers, and the .ifc file.

Problems with gdi, and DirectX header includes : C:\Program Files (x86)\Windows Kits\10\Include\10.0.22000.0\um\GdiplusEnums.h(27,13): warning C5260: the constant variable 'Gdiplus::FlatnessDefault' has internal linkage in an included header file context, but external linkage in imported header unit context; consider declaring it 'inline' as well if it will be shared across translation units, or 'static' to express intent to use it local to this translation unit; Multiple DirectX header includes with the same error.

I removed these includes, and was able to build the project.

Now, when I use

import "header.h";

I get

Error LNK1000 Internal error during IncrBuildImage

I am using the guide from cpp-build-msvc-170 p. 211-218

I took note of this:

Header units are a step in between header files and C++ 20 modules. They provide some of the benefits of modules. They're more robust because outside macro definitions don't affect them--so you can import them in any order. And the compiler can process them faster than header files. But header units don't have all of the advantages of modules because header units expose the macros defined within them (modules don't). Unlike modules, there's no way to hide private implementation in a header unit. To indicate private implementation with header files, different techniques are employed like adding leading underscores to names, or putting things in an implementation namespace. A module doesn't expose private implementation in any form, so you don't need to do that. Consider replacing your precompiled headers with header units. You get the same speed advantage, but with other code hygiene and flexibility benefits as well.

I tried using namespace, but I am not sure if I am going about it correctly, because when using namespace name in the main .cpp file the program crashes.

What is the correct way to do this, and what other techniques are they beside using underscores?

Thanks.

Minxin Yu 12,341 Reputation points Microsoft Vendor

2024-12-19T02:13:20.4633333+00:00

Can you provide a minimal reproducible example LNK1000? What is the content of header.h?
CDev-8220 220 Reputation points

2024-12-22T12:53:11.25+00:00

I'll see what I can do, but my time is limited at the moment, so that may be in a couple days.

CDev-8220 220

I got a few minutes to do do a bare minimum.

The import now works, but there remain the problem with various headers.

// HeaderBase.h
#pragma once

#define ADDHEADERS
//#define USINGGDI

#pragma region Base Headers

#include <SDKDDKVer.h>
#define WIN32_LEAN_AND_MEAN             
// Windows Header Files
#include <windows.h>
// C RunTime Header Files
#include <stdlib.h>
#include <malloc.h>
#include <memory.h>
#include <tchar.h>
#include "resource.h"

#pragma endregion // Base Headers

#pragma region Project Headers

#ifdef ADDHEADERS

#include <Winuser.h>
#pragma comment(lib, "User32.lib")

/* these headers cause errors if included after WindowsX.h */
#include <string> 
#include <stdio.h>
//#include <stdlib.h>
#include <fstream>
#include <sstream>
#include <iostream>

/* The contents of <filesystem> are available only
with C++17 or later */
#include <filesystem>

#include <dxgitype.h>

#include <WindowsX.h> // GET_X_LPARAM; GET_Y_LPARAM

#else

#include <atlbase.h> // Contains the declaration of CComPtr.
#include <atlconv.h>
// Error	LNK1000	Internal error during IncrBuildImage

#ifdef USINGGDI

#include <gdiplus.h>
#pragma comment(lib, "gdiplus.lib")
//#include <gdiplusheaders.h>
//#include <Gdiplusimaging.h>
//#include <gdiplusimagecodec.h>

#endif // USINGGDI
// multiple errors

#include <vector>
// Error	LNK1000	Internal error during IncrBuildImage

#include <DirectXMath.h>
#include <DirectXPackedVector.h>
#include <DirectXCollision.h>
/* multiple errors
Severity	Code	Description	Project	File	Line	Suppression State
Warning	C5260	the constant variable 'DirectX::XM_PI' has 
internal linkage in an included header file context, but 
external linkage in imported header unit context; consider 
declaring it 'inline' as well if it will be shared across 
translation units, or 'static' to express intent to use it 
local to this translation unit	
TestHeaders	C:\Program Files (x86)\Windows Kits\10\Include\10.0.22000.0\um\DirectXMath.h	242	 */

#endif // ADDHEADERS

#pragma endregion // Project Headers

// TestHeaders.cpp : Defines the entry point for the application.
#define CREATEHU

#ifdef CREATEHU

#include "HeaderBase.h"

#else

import "HeaderBase.h"; // this works now

#endif

#define MAX_LOADSTRING 100

// Global Variables:
HINSTANCE hInst; // current instance
WCHAR szTitle[MAX_LOADSTRING]; // The title bar text
WCHAR szWindowClass[MAX_LOADSTRING]; // the main window class name

// Forward declarations of functions included in this code module:
ATOM                MyRegisterClass(HINSTANCE hInstance);
BOOL                InitInstance(HINSTANCE, int);
LRESULT CALLBACK    WndProc(HWND, UINT, WPARAM, LPARAM);
INT_PTR CALLBACK    About(HWND, UINT, WPARAM, LPARAM);
int APIENTRY wWinMain(_In_ HINSTANCE hInstance,
                     _In_opt_ HINSTANCE hPrevInstance,
                     _In_ LPWSTR    lpCmdLine,
                     _In_ int       nCmdShow)
{
    UNREFERENCED_PARAMETER(hPrevInstance);
    UNREFERENCED_PARAMETER(lpCmdLine);
    // TODO: Place code here.
    // Initialize global strings
    LoadStringW(hInstance, IDS_APP_TITLE, szTitle, MAX_LOADSTRING);
    LoadStringW(hInstance, IDC_TESTHEADERS, szWindowClass, MAX_LOADSTRING);
    MyRegisterClass(hInstance);
    // Perform application initialization:
    if (!InitInstance (hInstance, nCmdShow))
    {
        return FALSE;
    }
    HACCEL hAccelTable = LoadAccelerators(hInstance, MAKEINTRESOURCE(IDC_TESTHEADERS));
    MSG msg;
    // Main message loop:
    while (GetMessage(&msg, nullptr, 0, 0))
    {
        if (!TranslateAccelerator(msg.hwnd, hAccelTable, &msg))
        {
            TranslateMessage(&msg);
            DispatchMessage(&msg);
        }
    }
    return (int) msg.wParam;
}

//
//  FUNCTION: MyRegisterClass()
//
//  PURPOSE: Registers the window class.
//
ATOM MyRegisterClass(HINSTANCE hInstance)
{
    WNDCLASSEXW wcex;
    wcex.cbSize = sizeof(WNDCLASSEX);
    wcex.style          = CS_HREDRAW | CS_VREDRAW;
    wcex.lpfnWndProc    = WndProc;
    wcex.cbClsExtra     = 0;
    wcex.cbWndExtra     = 0;
    wcex.hInstance      = hInstance;
    wcex.hIcon          = LoadIcon(hInstance, MAKEINTRESOURCE(IDI_TESTHEADERS));
    wcex.hCursor        = LoadCursor(nullptr, IDC_ARROW);
    wcex.hbrBackground  = (HBRUSH)(COLOR_WINDOW+1);
    wcex.lpszMenuName   = MAKEINTRESOURCEW(IDC_TESTHEADERS);
    wcex.lpszClassName  = szWindowClass;
    wcex.hIconSm        = LoadIcon(wcex.hInstance, MAKEINTRESOURCE(IDI_SMALL));
    return RegisterClassExW(&wcex);
}

//
//   FUNCTION: InitInstance(HINSTANCE, int)
//
//   PURPOSE: Saves instance handle and creates main window
//
//   COMMENTS:
//
//        In this function, we save the instance handle in a global variable and
//        create and display the main program window.
//
BOOL InitInstance(HINSTANCE hInstance, int nCmdShow)
{
   hInst = hInstance; // Store instance handle in our global variable
   HWND hWnd = CreateWindowW(szWindowClass, szTitle, WS_OVERLAPPEDWINDOW,
      CW_USEDEFAULT, 0, CW_USEDEFAULT, 0, nullptr, nullptr, hInstance, nullptr);
   if (!hWnd)
   {
      return FALSE;
   }
   ShowWindow(hWnd, nCmdShow);
   UpdateWindow(hWnd);
   return TRUE;
}

//
//  FUNCTION: WndProc(HWND, UINT, WPARAM, LPARAM)
//
//  PURPOSE: Processes messages for the main window.
//
//  WM_COMMAND  - process the application menu
//  WM_PAINT    - Paint the main window
//  WM_DESTROY  - post a quit message and return
//
//
LRESULT CALLBACK WndProc(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam)
{
    switch (message)
    {
    case WM_COMMAND:
        {
            int wmId = LOWORD(wParam);
            // Parse the menu selections:
            switch (wmId)
            {
            case IDM_ABOUT:
                DialogBox(hInst, MAKEINTRESOURCE(IDD_ABOUTBOX), hWnd, About);
                break;
            case IDM_EXIT:
                DestroyWindow(hWnd);
                break;
            default:
                return DefWindowProc(hWnd, message, wParam, lParam);
            }
        }
        break;
    case WM_PAINT:
        {
            PAINTSTRUCT ps;
            HDC hdc = BeginPaint(hWnd, &ps);
            // TODO: Add any drawing code that uses hdc here...
            EndPaint(hWnd, &ps);
        }
        break;
    case WM_DESTROY:
        PostQuitMessage(0);
        break;
    default:
        return DefWindowProc(hWnd, message, wParam, lParam);
    }
    return 0;
}

// Message handler for about box.
INT_PTR CALLBACK About(HWND hDlg, UINT message, WPARAM wParam, LPARAM lParam)
{
    UNREFERENCED_PARAMETER(lParam);
    switch (message)
    {
    case WM_INITDIALOG:
        return (INT_PTR)TRUE;
    case WM_COMMAND:
        if (LOWORD(wParam) == IDOK || LOWORD(wParam) == IDCANCEL)
        {
            EndDialog(hDlg, LOWORD(wParam));
            return (INT_PTR)TRUE;
        }
        break;
    }
    return (INT_PTR)FALSE;
}

1 answer

Darran Rowe 1,236 Reputation points

2024-12-15T23:54:54.1366667+00:00

Unfortunately, this is one of those circumstances where if you have to ask this question then you are not ready to do this.

If you really wish to try this though, I seriously suggest that digging deep into winnt.h and trying to make a coherant view of that file is the first stop. The reason why I mention trying to work with winnt.h is because it perfectly highlights all of the problems with the Windows headers. If an example of what I mean is required, find the definitions of the CONTEXT structure. For the current Windows headers, CONTEXT will be defined as one of four incompatible definitions based upon the predefined macros.

But I also feel that just rewriting these headers to be more C++ and module friendly will be a much easier task overall.
Please sign in to rate this answer.
CDev-8220 220 Reputation points

2024-12-17T10:57:08.9733333+00:00

Unfortunately, this is one of those circumstances where if you have to ask this question then you are not ready to do this.

I thought a way to get help, to learn, was asking questions.

I tried using precompiled headers, which is recommended for large projects, to optimize builds, but that was not working out, and so, I went to the MS docs for help, and came across this information.

I decided to try Header Units instead.

The reason why I mention trying to work with winnt.h is because it perfectly highlights all of the problems with the Windows headers. If an example of what I mean is required, find the definitions of the CONTEXT structure. For the current Windows headers, CONTEXT will be defined as one of four incompatible definitions based upon the predefined macros.

Did you mean typedef struct _WOW64_CONTEXT? Otherwise, I do not see a CONTEXT structure.

While it may "perfectly highlights all of the problems with the Windows headers", it does not, for me.

For the current Windows headers, CONTEXT will be defined as one of four incompatible definitions based upon the predefined macros.

?

I do not see what you are trying to point out.

It does not help me at all.

Thanks for your response, nonetheless.

Darran Rowe 1,236 Reputation points

2024-12-19T13:22:48.7866667+00:00

I thought a way to get help, to learn, was asking questions.

Yes, and sometimes the answer to those questions can be very complex that they are difficult to condense down into an answer suitable for these forums.

The original question was actually answered in my post.

What is the correct way to do this, and what other techniques are they beside using underscores?

But I also feel that just rewriting these headers to be more C++ and module friendly will be a much easier task overall.

Believe it or not, this was completely serious. As stated in Compare header units, modules and precompiled headers, in the table entry for header units.

"This is a new feature in C++20 that allows you to import 'well-behaved' header files as modules."

I emphasised the well-behaved here, because it is important. What made you determine that the Windows headers are well-behaved? The PDF linked to is a documentation dump of this Visual C++ documentation and includes this.

Well behaved isn't really properly defined, but the general idea is that they are header files that are not overly affected or even affected at all by macros. However, the Windows header files are massively affected by macros, even silently affected. These effects are so far reaching that some of the most fundamental types change. This is one of the main reasons my answer contained the direction to consider winnt.h and to try to get a coherant view out of this file.

The biggest skill needed for this kind of work, especially when diagnosing problems is involved, is the same skillset used for library writing. The definitions that the client sees must match the definitions that the library itself was compiled with. There are some rules about matching definitions and memory compatibility, but these would be important facts that are picked up via reading documentation and experience. I would always consider cppreference a very good source of this information if the standard itself is not an option. But the biggest task when making header units and modules is to make sure that the definitions of all types and functions exactly match the definitions that the library was built with. In the Windows API case, this is information given to us in the Windows headers itself.

It may be difficult to notice, but most of the bad behaviour for the Windows headers stems from it containing two API definitions for 4 platforms, currently. The API definitions are the Windows 32 bit API and the Windows 64 bit API. There is some divergance in the 32 bit API, where x86 is defined with the __stdcall calling convention, where 32 bit ARM is defined with __stdcall, but the compiler silently ignores this and it is replaced with __cdecl. So any header units created must be correct for the platform targeted.

The fact that crashes occur indicate that there is either something wrong with the type definitions, there is an ODR violation or there is something much more subtle going on. For this, the best tools to diagnose are the compiler and debugger themselves. Visual Studio's intellisense helps a lot too. But again, these are skills that require practice, and I'm sure I could write a book named "Effective diagnosis of ABI problems using the compiler and debugger."

This post is long, and this was only from the stuff that I thought immediately. I'm sure I could get a lot more written on this subject if I wanted.

Darran Rowe 1,236 Reputation points

2024-12-19T13:23:58.4266667+00:00

Wow, I wrote a pretty long post going into a lot of depth and the automated system just outright deleted it.

It seems like I am unable to help anymore on this subject.

RLWA32 46,191 Reputation points

2024-12-19T14:50:23.22+00:00

The overly aggressive site filtering makes these mistakes all the time. I have found that if you post about the problem with a link to the question you attempted to respond to with the Microsoft Q&A tag that a moderator will restore the improperly deleted item.

CDev-8220 220 Reputation points

2024-12-22T12:46:49.9433333+00:00

Thanks @Darran Rowe your long post did help, and you may have answered the question, but the answer, while it may be accurate does not help if I cannot find what you are pointing out.

For example, say someone walks up to you and asks where the nearest police station is, and you say, "Go down the street here, for about eight blocks, and make a left. Then walk until you see a red fire hydrant... etc."

You may give correct directions, but what if the person does not see a particular feature you mentioned, the person is nowhere, and still has to ask someone else.

I do appreciate your response. I do, but I don't see what you pointed out:

find the definitions of the CONTEXT structure. For the current Windows headers, CONTEXT will be defined as one of four incompatible definitions based upon the predefined macros.

But I also feel that just rewriting these headers to be more C++ and module friendly will be a much easier task overall.

I would gladly attempt to rewrite these headers, if I could find them, but I can't find the CONTEXT structure.

Perhaps that would help.

Darran Rowe 1,236 Reputation points

2024-12-22T14:41:30.74+00:00

For the 26100 version of the Windows SDK, (aka, the 24H2 SDK), the four definitions of CONTEXT are in winnt.h.

The headers does something C related, so it may be easy to miss. It combines the definition and a typedef into one.

typedef struct _CONTEXT { // CONTEXT members } CONTEXT, *PCONTEXT;

This is something for C only, C++ isn't affected by this. What this does is drops the requirement for need of identifying if something is a structure. Otherwise this would need to use the struct keyword to identify the type.

void do_something(struct _CONTEXT *);

This essentially defines the _CONTEXT structure and then typedefs it to CONTEXT.

The x64 version of the CONTEXT structure is defined on lines 4301-4418. The 32 bit ARM CONTEXT structure is defined on lines 5284-5342. The x86 CONTEXT structure is defined on lines 8520-8606. The ARM64 CONTEXT structure is initially defined as ARM64_NT_CONTEXT, this is on lines 6810-6880. Line 6890 is where ARM64_NT_CONTEXT is typedefed to CONTEXT.

The version of this structure that is used is chosen based upon the predefined macros of the compiler used to compile the header. Older versions of the Windows 11 headers will have the definitions earlier in the file, but not by much. The above still applies.

CDev-8220 220 Reputation points

2024-12-22T19:46:30.45+00:00

Thanks, but I must not have that version, because my file does not reflect anything close to that.

There is

_XSTATE_CONTEXT

_KERNEL_CET_CONTEXT

_DISPATCHER_CONTEXT

and all of them contain DWORDs

Thanks for your efforts though, and for walking with me.

Darran Rowe 1,236 Reputation points

2024-12-22T23:00:37.3633333+00:00

This is the whole reason why I stated that this was the 26100 version of the SDK and that earlier versions of the SDK will be at earlier lines.

To give two extra examples of this, but I am not going through the entire Windows SDK history, for the initial release of Windows 11 SDK (22000, or 21H2) then the following are the lines for the CONTEXT structure definitions for each architecture.

x64: 4203-4320 ARM: 5164-5222 ARM64: 6518-6588 (with the typedef on 6598) x86: 8198-8284

For Windows 11 22621 SDK (this would be the 22H2/23H2 versions of Windows 11), then the following are the lines for the definition of the structures for each architecture.

x64: 4206-4323 ARM: 5181-5239 ARM64: 6549-6619 (with the typedef on 6629) x86: 8236-8322

If there is a real struggle to find the definitions, then there is one more trick you can use. There is a function named RtlCaptureContext, and this is one of the ways that an application is able to generate a CONTEXT structure based on the current processor state. It is possible to use Visual Studio's intellisense to navigate from this function definition to the currently active CONTEXT structure.

Visual Studio has a Go To Definition feature, which is on the F12 key, or it can be accessed by right clicking.

If RtlCaptureContext is typed into a C++ source file:

the caret is placed in or near the function name:

and then F12 is pressed, or the mouse cursor is placed over the function name, the right mouse button is pressed and Go To Definition is selected, then Visual Studio will go to the definition for RtlCaptureContext. This is important here because this returns a pointer to the CONTEXT structure, and this is defined along with the CONTEXT structure itself. The Go To Definition will navigate to the RtlCaptureContext in the winnt.h header.

Go To Definition can then be used to go to the currently active CONTEXT structure. Also, DISPATCHER_CONTEXT is defined really close to CONTEXT and always has a pointer to the CONTEXT structure as part of it for x64, ARM and ARM64. So if that structure has been located then it should be very easy to find CONTEXT.

As an example of how close DISPATCHER_CONTEXT is to CONTEXT. This is for the x64 version.

22000: DISPATCHER_CONTEXT at 4378-4390, CONTEXT at 4203-4320 22621: DISPATCHER_CONTEXT at 4381-4393, CONTEXT at 4206-4323 26100: DISPATCHER_CONTEXT at 4476-4488, CONTEXT at 4301-4418

Because of the definition of DISPATCHER_CONTEXT, it will always be defined after CONTEXT. It doesn't need to be there, but the way CONTEXT is defined in winnt.h will give this result.

//x64 DISPATCHER_CONTEXT structure, exceprt from winnt.h. //Taken from the Windows 11 SDK version 10.0.26100.1742 //Lines 4476-4488. typedef struct _DISPATCHER_CONTEXT { DWORD64 ControlPc; DWORD64 ImageBase; PRUNTIME_FUNCTION FunctionEntry; DWORD64 EstablisherFrame; DWORD64 TargetIp; PCONTEXT ContextRecord; //Pointer to CONTEXT structure PEXCEPTION_ROUTINE LanguageHandler; PVOID HandlerData; struct _UNWIND_HISTORY_TABLE *HistoryTable; DWORD ScopeIndex; DWORD Fill0; } DISPATCHER_CONTEXT, *PDISPATCHER_CONTEXT;

Darran Rowe 1,236 Reputation points

2024-12-22T23:51:07.9266667+00:00

I almost forgot to mention, DISPATCHER_CONTEXT is not defined for x86.

Since this is for exception handling then it isn't that surprising since x86 exception handling is very different from x64, ARM and ARM64.
Sign in to comment

Use comments to ask for clarification, additional information, or improvements to the question.

Share via

How do I use Header Units with the Windows Desktop Application default template and resolve conflicts with headers?

1 answer

Your answer