Expand description
What counts as a change to a header, and what a header is cut into before it is merged.
Design: spec/cross-compile/08-sysroots.md section 8.3, the paragraph that says a change is a
change to the code and not to the bytes. 420 of glibc’s 498 installed headers differ in bytes
somewhere between 2.28 and 2.44 and only 210 of them differ in code, because glibc moves the
copyright line in every file every January and changed the licence URL in every file from
http to https in 2019. A merge that believed the bytes would write a conditional into twice
as many files as need one, and every one of those conditionals would be about a year.
So two texts are compared by their code: comments removed, blank lines dropped, continued lines joined, runs of spaces and tabs collapsed. The text that gets written out is still real header text, never a normalized form of one, and where releases agree on the code it is the newest release’s text that is written.
§Why a file is cut into logical lines and not into lines
Because the merge writes #if between two pieces and there are places that cannot have an
#if put in the middle of them. One is a macro definition continued with a backslash, where a
directive between the continuation lines is not a directive at all. Another is a directive
continued the same way. The third is a block comment that opens after some code and closes on a
later line, which glibc writes in every table of constants:
#define IN_EXCL_UNLINK 0x04000000 /* Exclude events on unlinked
objects. */
#define IN_MASK_ADD 0x20000000 /* Add to the mask. */A cut between those two lines puts the end of a comment at the top of a piece, and the release that does not take that piece is left with a comment that never closes and a file whose next several declarations are inside it. So a logical line runs until the line ends with no comment open and no backslash on it, and a conditional lands before it or after it and never inside it.
Comment-only and blank lines are not pieces of their own either. They attach to the code line below them, which is where the comment about it lives, so moving a declaration between releases moves its comment with it instead of leaving it stranded above a conditional.
Structs§
- Item
- One piece of a header: a logical line of code, with whatever comments and blank lines came immediately above it.
- Pieces
- A header cut into pieces, with the comments after the last piece kept separately.