[clang] a1d52fc - Clarify documentation for -funique-source-file-names.

[via cfe-commits]

Author: Peter Collingbourne
Date: 2025-04-15T13:03:58-07:00
New Revision: a1d52fcdca8bda4fe8c6652b2de83f408f4ad4f2

URL: https://github.com/llvm/llvm-project/commit/a1d52fcdca8bda4fe8c6652b2de83f408f4ad4f2
DIFF: https://github.com/llvm/llvm-project/commit/a1d52fcdca8bda4fe8c6652b2de83f408f4ad4f2.diff

LOG: Clarify documentation for -funique-source-file-names.



Reviewers: efriedma-quic, teresajohnson

Reviewed By: teresajohnson, efriedma-quic

Pull Request: https://github.com/llvm/llvm-project/pull/135832

Added: 
    

Modified: 
    clang/docs/UsersManual.rst

Removed: 
    


################################################################################
diff  --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst
index d4656a7e63c99..69256527f40c9 100644
--- a/clang/docs/UsersManual.rst
+++ b/clang/docs/UsersManual.rst
@@ -2301,11 +2301,31 @@ are listed below.
 
    When enabled, allows the compiler to assume that each object file
    passed to the linker has been compiled using a unique source file
-   name. This is useful for reducing link times when doing ThinLTO
+   path. This is useful for reducing link times when doing ThinLTO
    in combination with whole-program devirtualization or CFI.
 
-   A misuse of this flag will generally result in a duplicate symbol
-   error at link time.
+   The full source path passed to the compiler must be unique. This
+   means that, for example, the following is a usage error:
+
+   .. code-block:: console
+
+     $ cd foo
+     $ clang -funique-source-file-names -c foo.c
+     $ cd ../bar
+     $ clang -funique-source-file-names -c foo.c
+     $ cd ..
+     $ clang foo/foo.o bar/foo.o
+    
+   but this is not:
+
+   .. code-block:: console
+
+     $ clang -funique-source-file-names -c foo/foo.c
+     $ clang -funique-source-file-names -c bar/foo.c
+     $ clang foo/foo.o bar/foo.o
+
+   A misuse of this flag may result in a duplicate symbol error at
+   link time.
 
 .. option:: -fforce-emit-vtables