[Bug web/65700] New: Documentation of internals is inconsistent in itself and diverges from reality

["goswin-v-b at web dot de" <gcc-bugzilla at gcc dot gnu dot org>]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=65700

            Bug ID: 65700
           Summary: Documentation of internals is inconsistent in itself
                    and diverges from reality
           Product: gcc
           Version: unknown
            Status: UNCONFIRMED
          Severity: normal
          Priority: P3
         Component: web
          Assignee: unassigned at gcc dot gnu.org
          Reporter: goswin-v-b at web dot de

https://gcc.gnu.org/onlinedocs/gccint/Collect2.html says when collect2 is used
it generates a temporary file listing the constructors and destructors and that
the actual calls to the constructors are done from __main().

https://gcc.gnu.org/onlinedocs/gccint/Initialization.html now tells a quite
different storry, including the .ctros/.dtors that are actually used on
x86/x86_64. It still mentions __main() in connection with collect2 being used.

On ARM what actually happens is that there is a .init_array section and the
libc startup files are supposed to process that itself. Despite collect2 being
used there is no __main() function that gets called for this.
There is no .init section but still gcc does NOT insert a call to __main() when
compiling main() like the docs say it would.

Further the .init_array does not hold the constructors in reverse order. It
actually holds a automatic constructor generated by gcc first and then all the
functions manually declared as constructors. Care must be taken by the linker
script to sort them by priority or they are random. So in the case of ARM the
cinstructors need to be called in order, not in reverse order.

Overall I have to say the documentation confuses things more than it actually
helps. I don't know if that is because it hasn't been updated in a long time or
never was complete or internally consistent in the first place. But it sure
could use some love.

If they can't be improved please at least add a comment where they are outdated
or when they where last synced against the source so it becomes clear to the
reader where they are lacking.