[flang-commits] [flang] [flang][doc] Added information about `REAL(16)` math intrinsics support. (PR #87710)

[Slava Zakharin via flang-commits]

https://github.com/vzakhari created https://github.com/llvm/llvm-project/pull/87710

None

>From 8ad637e33cc36fd607a4f888b05d8b47ee0e0ca2 Mon Sep 17 00:00:00 2001
From: Slava Zakharin <szakharin at nvidia.com>
Date: Thu, 4 Apr 2024 14:20:19 -0700
Subject: [PATCH] [flang][doc] Added information about `REAL(16)` math
 intrinsics support.

---
 flang/docs/GettingStarted.md    | 10 +++++++++
 flang/docs/Real16MathSupport.md | 38 +++++++++++++++++++++++++++++++++
 flang/docs/index.md             |  1 +
 3 files changed, 49 insertions(+)
 create mode 100644 flang/docs/Real16MathSupport.md

diff --git a/flang/docs/GettingStarted.md b/flang/docs/GettingStarted.md
index 043804e5a1228f..1c85a6754b155b 100644
--- a/flang/docs/GettingStarted.md
+++ b/flang/docs/GettingStarted.md
@@ -304,6 +304,16 @@ Clang-like device linking pipeline.
 
 The same set of CMake variables works for Flang in-tree build.
 
+### Build options
+
+One may provide optional CMake variables to customize the build. Available options:
+
+* `-DFLANG_RUNTIME_F128_MATH_LIB=libquadmath`: enables build of
+  `FortranFloat128Math` library that provides `REAL(16)` math APIs
+  for intrinsics such as `SIN`, `COS`, etc. GCC `libquadmath`'s header file
+  `quadmath.h` must be available to the build compiler.
+  [More details](Real16MathSupport.md).
+
 ## Supported C++ compilers
 
 Flang is written in C++17.
diff --git a/flang/docs/Real16MathSupport.md b/flang/docs/Real16MathSupport.md
new file mode 100644
index 00000000000000..6ef29d80a86d14
--- /dev/null
+++ b/flang/docs/Real16MathSupport.md
@@ -0,0 +1,38 @@
+<!--===- docs/Real16MathSupport.md
+
+   Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+   See https://llvm.org/LICENSE.txt for license information.
+   SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+
+-->
+
+# Flang support for REAL(16) math intrinsics
+
+To support most `REAL(16)` (i.e. 128-bit float) math intrinsics Flang relies
+on third-party libraries providing the implementation.
+
+`-DFLANG_RUNTIME_F128_MATH_LIB=libquadmath` CMake option can be used
+to build `FortranFloat128Math` library that has unresolved references
+to GCC `libquadmath` library. Flang driver built with this option
+will automatically link `FortranFloat128Math` and `libquadmath` libraries
+to any Fortran program. This implies that `libquadmath` library
+has to be available in the standard library paths, so that linker
+can find it. The `libquadmath` library installation into Flang project
+distribution is not automatic in CMake currently.
+
+Testing shows that `libquadmath` versions before GCC-9.3.0 have
+accuracy issues, so it is recommended to distribute the Flang
+package with later versions of `libquadmath`.
+
+Care must be taken by the distributors of Flang package built
+with `REAL(16)` support via `libquadmath` because of its licensing
+under GNU Library General Public License. Moreover, static linking
+of `libquadmath` to the Flang users' programs may imply some
+restrictions/requirements. This document is not intended to give
+any legal advice on distributing such a Flang compiler.
+
+Flang compiler targeting systems with `LDBL_MANT_DIG == 113`
+may provide `REAL(16)` math support without `libquadmath`
+dependency, using standard `libc` APIs for `long double`
+data type. It is not recommended to use the above CMake option
+for building Flang compilers for such targets.
diff --git a/flang/docs/index.md b/flang/docs/index.md
index ed749f565ff1b8..4a0b145df10b0c 100644
--- a/flang/docs/index.md
+++ b/flang/docs/index.md
@@ -85,6 +85,7 @@ on how to get in touch with us and to learn more about the current status.
    Semantics
    f2018-grammar.md
    fstack-arrays
+   Real16MathSupport
 ```
 
 # Indices and tables