- \n
- Overview: Where we were, where we’re going.<\/a><\/li>\n
- Old Code, Old Problems: ‘fun’ code issues found while scaling out.<\/a><\/li>\n
- Rethinking Compiler Tooling: How can the compiler rise to the scaling problems?<\/a><\/li>\n
- A New Approach to Referencing an IFC.<\/a><\/li>\n
- Playing Nice With Precompiled Headers (PCH).<\/a><\/li>\n
- Selecting a Launch Project: REDACTED.<\/a><\/li>\n
- Looking Ahead: Throughput.<\/a><\/li>\n<\/ul>\n
Overview<\/span><\/h2>\n
Last time<\/a> we talked about how and why header units can be integrated into a large cross-platform codebase like Office. We discussed\nhow header units helped surface conformance issues (good) and expose and fix compiler bugs (good-ish).<\/p>\n
We talked about how we went about taking “baby steps” to integrate header units into smaller liblets\u2014we’re talking\nsomething on the order of 100s of header units. This blog entry is all about scale and how we move from 100s of header\nunits to 1000s of header units, including playing nicely with precompiled headers!<\/p>\n
Office’s header unit experiments continued by following the charge that we left you with in the last blog post: “Header\nUnit All the Things!”. From that perspective we were wildly successful! By the last count we were able to successfully\ncreate over 5000 header units from liblet public headers. The road to reach that milestone wasn’t always smooth, and\nwe’ll cover some of the challenges.<\/p>\n
We’d like to highlight that the recent release of MSVC 17.6.6<\/a> makes\nthis one of the best times to get started with header units! The release contains the full set of fixes that were\ndiscovered in cooperation with Office. The full set of fixes will also be available in 17.7.5 and 17.8 preview 2.<\/p>\n
Old Code, Old Problems<\/span><\/h2>\n
While scaling out we encountered quite a number of complications. Some fixes involved updating Office code, while\nothers needed to be solved on the compiler side. We’ll present just a few examples from each bucket.<\/p>\n
Symbolic Links<\/span><\/h3>\n
The way Office sources coalesce is a mix between sources populated by git and libraries populated by NuGet\npackages which are then linked into a build source tree via symbolic links. From a build perspective, this is extremely\nconvenient because you can decouple library updates from the sources and you can have one copy of library code shared\nacross multiple copies of the git sources.<\/p>\n
Symbolic links are interesting from a compiler perspective for two reasons: diagnostics and
#pragma once<\/code><\/a>. For source\nlocations, there are two options: use the symbolic link as the file name or use the physical file the link resolves to.\nWhen issuing diagnostics, the compiler tries to use the symbolic link location because that is what was provided on the\n\/I<\/code><\/a>\nline, but there are cases where you might want the physical file location.<\/p>\n#pragma once<\/code> is a whole other beast with respect to symbolic links. In the beginning, C-style include guards\nwere created as a method of preventing repeated file content<\/em>.#pragma once<\/code> came about as a method of\npreventing inclusion of the same file<\/em>. The distinction between file and content is part of the reason why#pragma\nonce<\/code> is difficult to standardize due to its reliance on filesystem vagaries to identify what it means to point to the\n“same file”.<\/p>\nConsider a small example:<\/p>\n
- \n
- Real file:
C:\\inc\\a.h<\/code> which contains a single#pragma once<\/code><\/li>\n- Symlink 1:
C:\\syms\\inc\\lib1\\a.h -> C:\\inc\\a.h<\/code><\/li>\n- Symlink 2:
C:\\syms\\inc\\lib2\\a.h -> C:\\inc\\a.h<\/code><\/li>\n<\/ul>\nFurther consider a header in
C:\\syms\\inc\\lib2\\b.h<\/code>:<\/p>\n#pragma once\r\n#include \"a.h\"<\/pre>\n
Then in our sources we have:<\/p>\n
#include \"lib1\/a.h\"\r\n#include \"lib2\/b.h\"<\/pre>\n
Let’s dive into what should happen here:<\/p>\n
- \n
- The compiler sees symlink #1 through
\"lib1\/a.h\"<\/code>, sees#pragma once<\/code> in the file content and records that fileC:\\syms\\inc\\lib1\\a.h<\/code> is associated with a pragma once.<\/li>\n- The compiler reads
\"lib2\/b.h\"<\/code> and sees an inclusion of\"lib2\/a.h\"<\/code>.<\/li>\n- Symlink #2 is then read and the compiler observes that
#pragma once<\/code> is in the file content and records that fileC:\\syms\\inc\\lib2\\a.h<\/code> is associated with a pragma once.<\/li>\n<\/ul>\nSee a problem?<\/p>\n
The fact that the compiler read the file content from symlink #2 is where things start to go wrong. What should\nhave happened is that the compiler unwraps the symbolic link to discover what the underlying file is and records the\nreal file as the owner of the pragma once, which is exactly what we did to solve the problem in normal compilation\nscenarios.<\/p>\n
How does the situation above play into header units? Header units need to work like a PCH where they record\nmacros and pragma state, which includes
#pramga once<\/code>. This means that the IFC needs to record symbolic\nlinks and their “unwrapped” files so that the compiler can properly enforce#pragma once<\/code>. After this work\nwas done, many more scenarios were unblocked in the Office build.<\/p>\nAs a side note: it is always better to rely on standard C++ features to prevent repeated file content\ninclusion and doing so side-steps the symbolic link problem entirely.<\/em><\/p>\n
Inconsistent Conditional Compilation<\/span><\/h3>\n
We called out the most critical source of issues in the first blog post: inconsistent conditional compilation. As\nthe experiment added projects we ran into an increasing number of conflicts. Individual projects, or sometimes\nisolated build nodes, couldn’t agree if the default char\ntype is unsigned<\/a>, if RTTI\nshould be enabled<\/a>, or if UNICODE support\nshould be set<\/a>, and that’s only in command line options!<\/p>\n
Across liblet headers there were also code level macros to detangle: conditional selection of a memory allocator,\nmasks for disallowed Windows SDK functions, plus the
ASSUME<\/code> macro example still hadn’t been resolved! Solving such\nproblems could require touching nearly every project in Office.<\/p>\nInternal Linkage<\/span><\/h3>\n
Declarations at namespace, including global, scope marked
static<\/code> have internal linkage. With textual includes\nthis isn’t an issue for declarations such asstatic const float pi = 3.14<\/code> because the contents of the header file become\npart of the translation unit. The source used to compile a header unit is a translation unit unto itself and thus the\ndefinition ofpi<\/code> will not be visible when it is imported. Fortunately, the fix is simple. Such data declarations\nshould be marked asinline constexpr<\/code>. However, after converting the constant declarations to beinline constexpr<\/code> we\nwere still seeing many unresolved symbols during linking. These issues ultimately required a compiler change so that\nIFC could contain the full initialization information for the data.<\/p>\nNaturally, the compiler had to account for the common case where global variables marked as
inline constexpr<\/code>\nshould have their values encoded into the actual IFC. In general, the compiler already does this for simpler values\nsuch as integral types, but more complex user-defined types or arrays of objects had to be accounted for. As a compiler optimization, the variable is only instantiated when it is referenced.\nMore specifically, the compiler will only materialize the initializer if the variable is odr-used.<\/p>\nMismatched Include Paths<\/span><\/h3>\n
Office has continued to utilize the
\/translateInclude<\/code><\/a>\nflag to consume header units without rewriting source code. For this to operate as expected the#include<\/code>\ndirectives in source must match what is specified by a\/headerUnit<\/code><\/a>\nswitch. In Office the most common issue was a reference that used the internal path to a header instead of the external\none.<\/p>\n - The compiler reads
- Symlink 1:
- Old Code, Old Problems: ‘fun’ code issues found while scaling out.<\/a><\/li>\n
![\"Image](\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2023\/09\/word-with-header-units.png\")
<\/p>\n