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

[Andrzej Warzyński 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
----------------
banach-space wrote:

>  I think this requirement of using Clang as the linker driver if the main is C changes the usability for users coming from XLF or gfortran. They now need to know what main is and select a linker driver or toggle the option accordingly.

I think there two wider questions here:
 * What is the interface that LLVM Flang is exposing to the end-user?
 * Is it compatible with GFortran, Classic Flang, XLF? If not, what are the differences?
 
This PR is more about polishing and documenting the current behavior rather than defining it. The actual design was inherited from https://github.com/flang-compiler/f18-llvm-project. 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 🙏🏻 

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