Question about header file naming and documentation

[Limezero]

Hey there, I'm browsing through the STL code, and a few headers with mysterious names keep popping up, like yvals_core.h and xutility. It's not exactly clear what these do from a first glance, given that they're thousands of lines long and their descriptions usually say something along the lines of "internal header" with no further explanation.

I get that end users aren't supposed to care/know about these, but I'd like to understand how this specific implementation of the standard library is architected, in case I ever end up contributing a feature or need to look into something. What does yvals stand for? Why is there a separate yvals and a yvals_core? I assume the headers with an x prepended to their name are specifically the internal ones, but then why is it xmemory and ymath? Why do some files have three x-s in their name, like xxxprec?

Is there any documentation on this that I could read somewhere? A "getting started" guide of sorts, maybe?

[cpplearner]

My understanding is that:

• yvals.h primarily contains definitions used by the runtime. It notably defines _ITERATOR_DEBUG_LEVEL which controls the presence of data structures for iterator debugging.
• yvals_core.h contains definitions used throughout the project. It's not part of yvals.h because some files must not depend on _ITERATOR_DEBUG_LEVEL.
• The x and y prefixes are legacy. I consider them meaningless.
• "Contribution Guidelines" is on @StephanTLavavej's TODO list, but he is busy on other tasks.

[Limezero]

Oh, yvals is for the preprocessor/macro stuff. Duh, should've noticed. That said, I'd still be interested in knowing what the x/y mean and where exactly "vals" came from (values?) if anybody knows.

And yeah, a set of contribution guidelines which explains the structure of STL, or even just a document that lists what's supposed to go where and why, would be a welcome addition imo. The wiki is a bit barren at the moment unfortunately, and a lot of it seems to be several years out of date.

[AlexGuteniev]

My guess is that "x" and "y" mean "internal" and "very internal", the characters choice is so that they are ordered last, and the names where invevnted when still trying to fit 8.3 file names and avoiding non-letter-or-digit. So xxxprec could afford xxx, and xmemory just one x.

Now the convention is __msvc_***.hpp, no new x-files expected. The new convention doesn't try to fit in limitations that are long obsolete, instead it is very suggestive about being internal, and the purpose.

For yvals vs yvals_core see core headers in the wiki of the repo.

[CaseyCarter]

My incredibly vague understanding is that y was used to prefix C library internal headers and x C++ library internal headers in ancient times. They certainly don't have that meaning - or any particular meaning other than "internal things" - today.

The best way to understand which internal headers are used for what is to look at where they're included. <xutility>, for example, is roughly "the parts of <iterator> and <algorithm> needed by everything else", and <xmemory> is "the parts of <memory> needed by the container implementations." yvals_core is general configuration included by literally everything.

We don't have any documentation yet written up. Asking in Discord might be the easiest way to find things out.

[jovibor]

My incredibly vague understanding is that y was used to prefix C library internal headers and x C++ library internal headers in ancient times. They certainly don't have that meaning - or any particular meaning other than "internal things" - today.

Is it feasible to bring it all (rename) to one common pattern __msvc_***.hpp? Or does it have some internal difficulties?
It would be way more user friendly for new contributors and overall.

[Limezero]

I think that's most of my questions answered then, thank you everyone. The DOS filename limitation makes perfect sense, I guess the UCRT rework and the repo being on GitHub made me forget just how old some of this code is.

Personally I wouldn't mind a separate msvc directory altogether so there's a clear separation between the standard/internal headers, but I agree that the underscores are a better convention than using very standard-sounding filenames that happen to start with an x.

Feel free to close this issue or keep it around for tracking, depending on what you want.

[StephanTLavavej]

@jovibor

Is it feasible to bring it all (rename) to one common pattern __msvc_***.hpp? Or does it have some internal difficulties? It would be way more user friendly for new contributors and overall.

There's nothing physically stopping us from doing that, but there's a minor headache when renaming files (we have to go update a bunch of lists mentioned in the "hack these files" checklist), and a major headache when we find users who were directly including STL-internal headers. Just removing/fusing away <xstddef> led to some breakage we had to clean up. For <xutility> etc. we know for a fact that Windows-internal code is including those headers. There's a ton of such code and updating it is very time-consuming.

Even in the best of times, this would be a lot of effort for minimal value. Right now, maintainer capacity is extremely limited and I don't think we can afford to spend any on such renames.

[StephanTLavavej]

Closing as this question has been answered - and we remembered that #354 is already tracking a potential renaming pass.