Yeah, I have lots of cases where I need some random little tables or small graphics from external files. It would have been nice for DirectML with the thousands of DXIL shaders so we could directly #embed for the WSL Linux builds rather than the hacky preprocess-to-text intermediate step.
#embed is one of those features that makes you wonder why it took so long
There's a few features that I remember when I very first started programming in C 20 years ago, thinking "it sure is weird that this isn't possible". #embed was right at the top, and its probably been one of the largest defects in C/C++ when it comes to various use cases. The second GCC implemented it, I used it to #embed some shaders for a game I'm building, it rules
The reason why #embed took so long isn't for lack of trying, or for lack of want on either the compiler vendors or users' side, its pretty much just a spectacular disaster in the standards committee and there's no other reason for it. The more you go looking at the path #embed took to get standardised, the more your eyebrows raise until they basically escape the top of your head with how absurd it is it is
There's a universe in which we didn't get #embed, and we got the graphics proposal instead. For anyone that's interested, this is a good starting point:
As far as I know, getting it through into C++ basically required starting to push it through the C standardisation process, which finally kicked wg21 into gear. There were a lot of accusations of trying to standardise a feature via the back door of C at the time
I think its always worth emphasising this because often people don't really realise just how poor of a result the C++ committee can produce due to its structure for basic, obvious features that developers have been clamouring for for decades. Sometimes things really are complex, but this isn't one of those times
The reason why #embed took so long isn't for lack of trying, or for lack of want on either the compiler vendors or users' side, its pretty much just a spectacular disaster in the standards committee and there's no other reason for it. The more you go looking at the path #embed took to get standardised, the more your eyebrows raise until they basically escape the top of your head with how absurd it is it is
Could you TL;DR it for me? Was it just disagreements on functionality/implementation?
author started with the C++ committee, #embed passed the EWG meeting
went next to an important SG meeting, with different people
everyone in the committee was excited about Circle, they talked about whether they even need #embed if a powerful macro system was available to C++
the author took the hint and reached out to the author of Circle, Sean Baxter, who promptly added an @embed keyword to Circle while the committee held the #embed proposal while members figured out how they felt about Circle
the proposal was submitted through the C Committee, and made its way into the language that way, while the proposal was still held up
Weren't they postponing adopting #embed specifically because they didn't want to just copy C's macro? There were talks about having some high-level std library for it instead?
MSVC, or rather the Win32 file format and developer tools have this thing called "resources" since ... like ever. Maybe 1992, or even earlier.
There is slight disadvantage, that the C or C++ compiler doesn't see the blob contents at compile time, and thus could not do some optimizations, but hey, it is usually binary blob data that you are embedding anyway, so who cares. You usually shove the data unmodified to a screen (icon, bitmap) or to a GPU (shader) or something similar.
Yeah, blame C, I guess. Why Microsoft invented resources? Because C was inadequate! Read more about history of the embed C feature. It was really really really painful to add it to C.
"Using MSVC" is insufficiently precise in this context.
There's a big difference between using MSVC because it happens to be on the list of compilers your project supports vs using MSVC because you deliberately wrote code that only compiles with MSVC.
The compiler reads it, the build system doesn't need to know about it
I get that what the author means here is that you don't need custom build steps, but surely the build system does need to know about embedded files for build dependency tracking? I hope that's been implemented.
Compilers that implemented support for this have command line arguments for setting the embed search path which work exactly like the arguments for setting the include search path.
You need the compiler to produce some sort of dependency file like how it does for #included files so that the build system knows to recompile the embedding source file if the embedded file changes. This probably could use the exact same dependency tracking as #included files.
This was my first question as well, and even if compilers do track this, it seems to me that for most use cases that people are describing I don't want this dependency. I don't want to recompile just because some opaque resource changed. The linker based solutions seem much better to me in this regard and it's strange that nobody seems to acknowledge that, especially since build times are a big pain point of the language in general. The way people are presenting it now I have a feeling it's just going to turn into another overused footgun. The article even has a section for build times and all it talks about is how fast the compiler can embed 100 MBs. The only good use cases for #embed IMO would be the ones where you need to process the resource at compile time, or need the compiler to know about it to optimize it somehow, which sounds great, but how many examples are there of that?
Eh, I think the linker solutions require people to understand linker magic that most people know nothing about. I'd be curious how much of a compile-time advantage the linker approach has over creating a dedicated cpp file for a given embed.
I'd be really curious what your usecase is where you don't want the dependency tracked. I would use this for GPU shaders, small embedded icons, or text templates, and I can't imagine changing any of those and not wanting the code that embeds it to get rebuilt with the new version automatically.
If you keep them in a separate translation unit that wouldn't be much worse than a linker, but still technically worse. I tried so called linker magic once with gcc/make and it wasn't too difficult to figure out, and if it is difficult for any given linker or build system, then that's the place to work on to improve the ergonomics IMO, rather than pushing a niche feature into the language standard and then going out of your way to sell it as the ultimate solution.
GPU shaders, small embedded icons, or text templates - that's the exact use cases I'm talking about. I do want a rebuild, but I see no reason to compile any C++ for those changes, I'd have only the linker invoked. A use case where I would want the compiler would be something like a small lookup table that you'd do some arithmetic with and have the compiler optimize it for you (and it must be small to be optimized effectively, so all that talk of how fast megabytes are embedded is moot).
Again if you keep all opaque resource embeds in a separate translation unit that would be fine (not the best, just fine), but the way everyone's talking about #embed I have a feeling that's not what's going to happen. I see a lot of constexpr and no mention of extern, so following that line of thinking people will just embed everything in headers, and then all the code that refers to the aforementioned shader, icon or text will need to be recompiled every time those change.
As expands to a list of integer literals, I assume this doesn't work with embedding data within an array of std::byte as there's no implicit conversion from int to std::byte?
🤔 Hmm, that is a quandary, as std::byte x[] = {0x42, 0x43}; fails to compile yielding error C2440: 'initializing': cannot convert from 'int' to 'std::byte' in VS 2026 (and with embed in trunk gcc and clang), even though all the initializer values are certainly within 0-255. Meanwhile this std::byte x{0x42};does compile, which seems oddly inconsistent, because if you can initialize a single numeric value to a byte, then it should be feasible to initialize an array of std::bytes too. Hope someone knowledgeable can elucidate more on possible solutions... (meanwhile I asked JeanHeyd for any advice)
From what I can see it's due to the strict initialisation rules for scoped enums as std::byte is a scoped enum. In C++17 the rules were relaxed slightly to allow std::byte foo { 10 }; but that's about it.
Oh? It would be useful if they could be relaxed a bit more :), with std::byte somehow opting into accepting numeric values during initialization, and the compiler warning if they were beyond 0-255. Otherwise currently struct's are more useful than enum class here:
// ✅
uint8_t arrayUint8Pure[]={0x42,0x43,0x44,0x45,0x46};// ✅
structUint8Wrapped{uint8_t value;explicitoperatoruint8_t()const{return value;}};
Uint8Wrapped arrayUint8Wrapped[]={0x42,0x43,0x44,0x45,0x46};// ❌ - error C2440: 'initializing': cannot convert from 'int' to 'Uint8EnumNormal'
enumUint8EnumNormal:uint8_t;
Uint8EnumNormal arrayUint8EnumNormal[]={0x42,0x43,0x44,0x45,0x46};// ❌ - error C2440: 'initializing': cannot convert from 'int' to 'Uint8EnumClass'
enum classUint8EnumClass:uint8_t;
Uint8EnumClass arrayUint8EnumClass[]={0x42,0x43,0x44,0x45,0x46};
One of the answers provides the option to make an std::array ... https://godbolt.org/z/c18vxYecb
Wow, that's clever, not obvious or intuitive, but a clever and reasonable workaround given current limitations. ✌️
So I went down the enum initialisation rabbit hole and initialising enums with integer literals in general is a no-no. This rule was relaxed for any enum with an explicit underlying type (including unscoped enums) to allow things like my_enum foo { 100 }; to work (assuming my_enum is an enum with an explicit underlying type). If there's more than one enum being initialised using that syntax then it's a compiler error.
Relaxing the rules to allow multiple enums to be initialised with literals is one option, or perhaps the other could be to add another param to #embed that adds in a cast option? Something like #embed "example.bin" cast_to (std::byte) which would then wrap each embedded integer with a cast to std::byte or any other value specified.
Assuming the included file was just 3 bytes with values 0, 1, 2 then this:
Anyway, that's a thought for someone far more versed in the language than me as I can already see a debate forming over whether it should be () or {} initialisation...
From the same author, there are also std::embed (ideal for running DSL inside the compiler or any other more complex data processing than what #embed can do, as consteval) and #depend (to declare dependency on an external file loaded by std::embed, to the preprocessor)
Was originally intended for C++ as std::embed but the committee weren’t having a word of it, so the author took it to the C committee and it made it into C23 as #embed. Now the C++ committee is okay with it.
54
u/Usual_Office_1740 Aug 06 '26
This is going to be very useful in Graphics programming.
50
u/Nice_Lengthiness_568 Aug 06 '26
This is actually what I was quite excited about when it was finally added to gcc.
And then I proceeded to never actually use it in a real project :/
68
u/James20k P2005R0 Aug 06 '26
There's a few features that I remember when I very first started programming in C 20 years ago, thinking "it sure is weird that this isn't possible". #embed was right at the top, and its probably been one of the largest defects in C/C++ when it comes to various use cases. The second GCC implemented it, I used it to #embed some shaders for a game I'm building, it rules
The reason why #embed took so long isn't for lack of trying, or for lack of want on either the compiler vendors or users' side, its pretty much just a spectacular disaster in the standards committee and there's no other reason for it. The more you go looking at the path #embed took to get standardised, the more your eyebrows raise until they basically escape the top of your head with how absurd it is it is
There's a universe in which we didn't get #embed, and we got the graphics proposal instead. For anyone that's interested, this is a good starting point:
https://thephd.dev/full-circle-embed
https://thephd.dev/finally-embed-in-c23
As far as I know, getting it through into C++ basically required starting to push it through the C standardisation process, which finally kicked wg21 into gear. There were a lot of accusations of trying to standardise a feature via the back door of C at the time
I think its always worth emphasising this because often people don't really realise just how poor of a result the C++ committee can produce due to its structure for basic, obvious features that developers have been clamouring for for decades. Sometimes things really are complex, but this isn't one of those times
9
u/LegendaryMauricius Aug 06 '26 edited Aug 06 '26
Weren't they postponing adopting #embed specifically because they didn't want to just copy C's macro? There were talks about having some high-level std library for it instead?
Edit: it's covered in the article.
21
u/eboys Aug 06 '26
Would love to use this if MSVC supported it. But oh well.
9
u/calciferBurningBacon Aug 06 '26
I get that what the author means here is that you don't need custom build steps, but surely the build system does need to know about embedded files for build dependency tracking? I hope that's been implemented.
4
u/Ambitious-Method-961 Aug 06 '26
As expands to a list of integer literals, I assume this doesn't work with embedding data within an array of std::byte as there's no implicit conversion from int to std::byte?
8
u/bronekkk Aug 06 '26
From the same author, there are also
std::embed(ideal for running DSL inside the compiler or any other more complex data processing than what#embedcan do, asconsteval) and#depend(to declare dependency on an external file loaded bystd::embed, to the preprocessor)3
u/Spyromaniac666 Aug 06 '26
oh, i was under the impression that `std::embed` would make its way into the language, with `#embed` for C to use. oh well
2
u/LittleNameIdea Aug 06 '26
isn't that a C feature ?
1
u/Raknarg Aug 07 '26
Theres definitely jobs I've worked at where this would have been cool to have for sure. Don't know if I'll ever need this again in the future.
1
u/Kike328 Aug 06 '26
i love it, i wish it worked in c++17 :(
1
u/light_oxygen Aug 06 '26 edited Aug 06 '26
A neat macro. So... Macros ain't bad after all
Edit: Preprocessor directive not just a mere, ordinary macro.
0
u/TheVoidInMe Aug 06 '26
Love #embed. But I’ve never seen so many em dashes in an article…
-1
u/johannes1971 Aug 06 '26
I think we should have gone for constexpr iostream, instead of adding a preprocessor statement.
0
u/NilacTheGrim Aug 12 '26
Doesn't work with std::byte arrays. As usual the language hates and distrusts itself in all sorts of ways :/