[llvm] [llvm-link] Add more detail to `--internalize` description (PR #170397)

[via llvm-commits]

llvmbot wrote:


<!--LLVM PR SUMMARY COMMENT-->

@llvm/pr-subscribers-llvm-binary-utilities

Author: Matthew Maurer (maurer)

<details>
<summary>Changes</summary>

While the functionality of this flag is obvious in the implementation, tool users may not know what it does with the short description provided. Notably, it is not obvious from the short description that:

* Functions provided will be converted to internal linkage (and thus discarded if unused) even if unreferenced.
* Functions in the first file will not be internalized, even if referenced by a later one.

The Rust for Linux project has [found use for this flag](https://lore.kernel.org/all/20251202-inline-helpers-v1-0-879dae33a66a@<!-- -->google.com/) to support inlining `static inline` functions in C into code compiled by Rust when `rustc` and `clang` share a LLVM.

I wanted to send this PR both to:
1. Help others find the flag in the future
2. Clarify that our understanding of what we can rely upon this option to do is correct, and not just what the implementation happens to do at the moment.

cc @<!-- -->Darksonn (also with Rust-for-Linux)

cc @<!-- -->nikic Perhaps able to review or route us to an appropriate reviewer?

---
Full diff: https://github.com/llvm/llvm-project/pull/170397.diff


2 Files Affected:

- (modified) llvm/docs/CommandGuide/llvm-link.rst (+4-1) 
- (modified) llvm/tools/llvm-link/llvm-link.cpp (+6-3) 


``````````diff
diff --git a/llvm/docs/CommandGuide/llvm-link.rst b/llvm/docs/CommandGuide/llvm-link.rst
index 1cc1376becf9d..ba6eee5b71be4 100644
--- a/llvm/docs/CommandGuide/llvm-link.rst
+++ b/llvm/docs/CommandGuide/llvm-link.rst
@@ -71,7 +71,10 @@ OPTIONS
 
 .. option:: --internalize
 
-  Internalize the linked symbols.
+  Maintains existing linkage for symbols defined in the first input and
+  converts linkage in all other inputs to internal linkage unless they are
+  referenced by `llvm*.used` or are special-cased runtime functions (e.g.
+  stack protector runtime).
 
 .. option:: --disable-debug-info-type-map
 
diff --git a/llvm/tools/llvm-link/llvm-link.cpp b/llvm/tools/llvm-link/llvm-link.cpp
index 33c3e6fc350fb..fbc6c31f75c62 100644
--- a/llvm/tools/llvm-link/llvm-link.cpp
+++ b/llvm/tools/llvm-link/llvm-link.cpp
@@ -75,9 +75,12 @@ static cl::opt<std::string>
     OutputFilename("o", cl::desc("Override output filename"), cl::init("-"),
                    cl::value_desc("filename"), cl::cat(LinkCategory));
 
-static cl::opt<bool> Internalize("internalize",
-                                 cl::desc("Internalize linked symbols"),
-                                 cl::cat(LinkCategory));
+static cl::opt<bool>
+    Internalize("internalize",
+                cl::desc("Internalize linked symbols - maintains existing "
+                         "linkage for the first input and converts linkage in"
+                         " all other inputs to `internal`"),
+                cl::cat(LinkCategory));
 
 static cl::opt<bool>
     DisableDITypeMap("disable-debug-info-type-map",

``````````

</details>


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