[flang] [clang] [flang][driver] Remove Fortain_main static library from linking stages (PR #75816)

[Michael Klemm via cfe-commits]

================
@@ -163,6 +163,40 @@ forward compiler options to the frontend driver, `flang-new -fc1`.
 You can read more on the design of `clangDriver` in Clang's [Driver Design &
 Internals](https://clang.llvm.org/docs/DriverInternals.html).
 
+## Linker Driver
+When used as a linker, Flang's frontend driver assembles the command line for an
+external linker command (e.g., LLVM's `lld`) and invokes it to create the final
+executable by linking static and shared libraries together with all the
+translation units supplied as object files.
+
+By default, the Flang linker driver adds several libraries to the linker
+invocation to make sure that all entrypoints for program start
+(Fortran's program unit) and runtime routines can be resolved by the linker.
+The libraries are:
+
+* `Fortran_main`: Provides the main entry point `main` that then invokes
+  `_QQmain` with the Fortran program unit.  This library has a dependency to
+  the `FortranRuntime` library.
+* `FortranRuntime`: Provides most of the Flang runtime library.
+* `FortranDecimal`: Provides operations for decimal numbers.
+
+The default is that, when using Flang as the linker, one of the Fortran
+translation units provides the program unit and therefore it is assumed that
+Fortran is the main code part (calling into C/C++ routines via `BIND
+(C)` interfaces).  When composing the linker commandline, Flang uses
+`--whole-archive` and `--no-whole-archive` (Windows: `/WHOLEARCHIVE:`,
+Darwin: *not implemented yet*) to make sure that all for `Fortran_main` is
+processed by the linker.  This is done to issue a proper error message when
+multiple definitions of `main` occur.  This happens, for instance, when linking
+a code that has a Fortran program unit with a C/C++ code that also defines a
+`main` function.
+
+If the code is C/C++ based and invokes Fortran routines, either use Clang as the
+linker driver (supplying `FortranRuntime` and/or `FortranDecimal` to the linker
----------------
mjklemm wrote:

> It could be updated, but that should probably be raised on Discourse or in the community call. Having said, documenting this is long overdue and I am super grateful that Michael is doing this for us 🙏🏻

I fully agree.  The good thing is: it's not defined in any (ISO) standard, so we can do whatever we like and what we think is useful behavior in the end.  I'd like to note that the introduction of `-fno-fortran-main` can still be useful with a behavior that is similar to GFortran (emitting the actual `main` code in the translation unit with a program statement), but would then turn `-fno-fortran-main` flag into a more corner-case, expert type flag.

I'd suggest to get current behavior cleanly merged for the 18.0 branch and then re-think this somewhat more for the 19.0 release and the future.  At least now, we will have documented and well-defined behavior.  If it's the right one, we can debate. :-)

https://github.com/llvm/llvm-project/pull/75816