[llvm] [DOC][DTLTO] Update DTLTO documentation for the LLVM 22 release (PR #177368)
Ben Dunbobbin via llvm-commits
llvm-commits at lists.llvm.org
Fri Jan 30 07:31:59 PST 2026
https://github.com/bd1976bris updated https://github.com/llvm/llvm-project/pull/177368
>From 1644c7bd6531d2897965cb479b9c5ffd15b1899a Mon Sep 17 00:00:00 2001
From: Ben <ben.dunbobbin at sony.com>
Date: Thu, 22 Jan 2026 14:17:57 +0000
Subject: [PATCH 1/6] [DOC][DTLTO] Update DTLTO documentation for the LLVM 22
release
This change updates the documentation to reflect work completed during
the LLVM 22 timeframe, including support for the ThinLTO cache and
static libraries and archives.
It also clarifies that the goal of DTLTO is to support distribution of
ThinLTO backend compilations for any in-process ThinLTO invocation.
SIE Internal Tracker: TOOLCHAIN-21016
---
llvm/docs/DTLTO.rst | 13 +++++++------
1 file changed, 7 insertions(+), 6 deletions(-)
diff --git a/llvm/docs/DTLTO.rst b/llvm/docs/DTLTO.rst
index 70e26efed897e..04cb4935952c7 100644
--- a/llvm/docs/DTLTO.rst
+++ b/llvm/docs/DTLTO.rst
@@ -11,7 +11,7 @@ DTLTO
Distributed ThinLTO (DTLTO)
===========================
-Distributed ThinLTO (DTLTO) enables the distribution of backend ThinLTO
+Distributed ThinLTO (DTLTO) enables the distribution of ThinLTO backend
compilations via external distribution systems, such as Incredibuild, during the
link step.
@@ -24,7 +24,11 @@ here:
Using the *separate thin-link* approach requires a build system capable of
handling the dynamic dependencies specified in the individual summary index
files, such as Bazel. DTLTO removes this requirement, allowing it to be used
-with any build process that supports in-process ThinLTO.
+with any build process that supports in-process ThinLTO. Note that, to
+facilitate this, DTLTO aims to support all in-process ThinLTO features, such as
+caching (for incremental builds), and aims to support all linker input file
+types, including static libraries/archives (e.g. libc.a), rather than being
+limited to plain bitcode files.
The following commands show the steps used for the *separate thin-link*
approach for a basic example:
@@ -66,7 +70,7 @@ such as the following can be used:
.. code-block:: console
- clang -flto=thin -fuse-ld=lld -O2 t1.o t2.o -fthinlto-distributor=$(which python3) \
+ clang -flto=thin -fuse-ld=lld -O2 t1.o t2.o libt3.a -fthinlto-distributor=$(which python3) \
-Xthinlto-distributor=$LLVMSRC/llvm/utils/dtlto/local.py
Distributors
@@ -170,9 +174,7 @@ TODOs
The following features are planned for DTLTO but not yet implemented:
-- Support for the ThinLTO in-process cache.
- Support for platforms other than ELF and COFF.
-- Support for archives with bitcode members.
- Support for more LTO configurations; only a very limited set of LTO
configurations is supported currently, e.g., support for basic block sections
is not currently available.
@@ -183,4 +185,3 @@ Constraints
- Matching versions of Clang and LLD should be used.
- The distributor used must support the JSON schema generated by the version of
LLD in use.
-
>From 7f310514f3ae39f22c37ba5c7869171a49bc2ad1 Mon Sep 17 00:00:00 2001
From: Ben Dunbobbin <Ben.Dunbobbin at sony.com>
Date: Thu, 22 Jan 2026 15:34:01 +0000
Subject: [PATCH 2/6] Update llvm/docs/DTLTO.rst
Co-authored-by: Edd Dawson <edd.dawson at sony.com>
---
llvm/docs/DTLTO.rst | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/llvm/docs/DTLTO.rst b/llvm/docs/DTLTO.rst
index 04cb4935952c7..4e5dbe5c0e724 100644
--- a/llvm/docs/DTLTO.rst
+++ b/llvm/docs/DTLTO.rst
@@ -25,10 +25,10 @@ Using the *separate thin-link* approach requires a build system capable of
handling the dynamic dependencies specified in the individual summary index
files, such as Bazel. DTLTO removes this requirement, allowing it to be used
with any build process that supports in-process ThinLTO. Note that, to
-facilitate this, DTLTO aims to support all in-process ThinLTO features, such as
-caching (for incremental builds), and aims to support all linker input file
-types, including static libraries/archives (e.g. libc.a), rather than being
-limited to plain bitcode files.
+facilitate this, DTLTO aims to support common in-process ThinLTO features, such
+as caching. Archived bitcode objects are also handled transparently by
+temporarily extracting referenced objects for distribution. If thin archives
+are used, extraction is not needed.
The following commands show the steps used for the *separate thin-link*
approach for a basic example:
>From a83efd9027ae51f5fa37241642e4f80c3415c624 Mon Sep 17 00:00:00 2001
From: Ben <ben.dunbobbin at sony.com>
Date: Thu, 22 Jan 2026 16:01:08 +0000
Subject: [PATCH 3/6] Add TODO that cache entries are not yet shared between
TLTO and DTLTO.
- Polish wording.
- Remove unnecessary change.
---
llvm/docs/DTLTO.rst | 15 +++++++++------
1 file changed, 9 insertions(+), 6 deletions(-)
diff --git a/llvm/docs/DTLTO.rst b/llvm/docs/DTLTO.rst
index 4e5dbe5c0e724..45e6b3ace2517 100644
--- a/llvm/docs/DTLTO.rst
+++ b/llvm/docs/DTLTO.rst
@@ -11,7 +11,7 @@ DTLTO
Distributed ThinLTO (DTLTO)
===========================
-Distributed ThinLTO (DTLTO) enables the distribution of ThinLTO backend
+Distributed ThinLTO (DTLTO) enables the distribution of backend ThinLTO
compilations via external distribution systems, such as Incredibuild, during the
link step.
@@ -24,11 +24,11 @@ here:
Using the *separate thin-link* approach requires a build system capable of
handling the dynamic dependencies specified in the individual summary index
files, such as Bazel. DTLTO removes this requirement, allowing it to be used
-with any build process that supports in-process ThinLTO. Note that, to
-facilitate this, DTLTO aims to support common in-process ThinLTO features, such
-as caching. Archived bitcode objects are also handled transparently by
-temporarily extracting referenced objects for distribution. If thin archives
-are used, extraction is not needed.
+with any build process that supports in-process ThinLTO. To facilitate this,
+DTLTO supports common in-process ThinLTO features, such as caching. Bitcode
+objects in static libraries/archives (e.g., libc.a) are also handled
+transparently by temporarily extracting referenced objects for distribution;
+when thin archives are used, no extraction is required.
The following commands show the steps used for the *separate thin-link*
approach for a basic example:
@@ -178,6 +178,9 @@ The following features are planned for DTLTO but not yet implemented:
- Support for more LTO configurations; only a very limited set of LTO
configurations is supported currently, e.g., support for basic block sections
is not currently available.
+- Support for sharing ThinLTO cache entries with in-process ThinLTO entries.
+ This is not currently supported because identical code generation is not yet
+ guaranteed.
Constraints
-----------
>From acb6b3a49240393d55cf94ebb8068f9fc0faf9f6 Mon Sep 17 00:00:00 2001
From: Ben Dunbobbin <Ben.Dunbobbin at sony.com>
Date: Thu, 22 Jan 2026 19:25:33 +0000
Subject: [PATCH 4/6] Update DTLTO.rst
Remove comma from e.g., construct on the advice of an actual American English speaker.
---
llvm/docs/DTLTO.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/llvm/docs/DTLTO.rst b/llvm/docs/DTLTO.rst
index 45e6b3ace2517..8188efa1e81df 100644
--- a/llvm/docs/DTLTO.rst
+++ b/llvm/docs/DTLTO.rst
@@ -26,7 +26,7 @@ handling the dynamic dependencies specified in the individual summary index
files, such as Bazel. DTLTO removes this requirement, allowing it to be used
with any build process that supports in-process ThinLTO. To facilitate this,
DTLTO supports common in-process ThinLTO features, such as caching. Bitcode
-objects in static libraries/archives (e.g., libc.a) are also handled
+objects in static libraries/archives (e.g. libc.a) are also handled
transparently by temporarily extracting referenced objects for distribution;
when thin archives are used, no extraction is required.
>From 2f30a9e4d1c9d4d57e0f3ac0a98f4a439a959cc2 Mon Sep 17 00:00:00 2001
From: Ben Dunbobbin <Ben.Dunbobbin at sony.com>
Date: Mon, 26 Jan 2026 09:44:13 +0000
Subject: [PATCH 5/6] Update DTLTO.rst
Use e.g. (as opposed to e.g.,) everywhere in the document.
---
llvm/docs/DTLTO.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/llvm/docs/DTLTO.rst b/llvm/docs/DTLTO.rst
index 8188efa1e81df..443c9e2a137e6 100644
--- a/llvm/docs/DTLTO.rst
+++ b/llvm/docs/DTLTO.rst
@@ -176,7 +176,7 @@ The following features are planned for DTLTO but not yet implemented:
- Support for platforms other than ELF and COFF.
- Support for more LTO configurations; only a very limited set of LTO
- configurations is supported currently, e.g., support for basic block sections
+ configurations is supported currently, e.g. support for basic block sections
is not currently available.
- Support for sharing ThinLTO cache entries with in-process ThinLTO entries.
This is not currently supported because identical code generation is not yet
>From f7493e434be52741229c5e0f206d34c89c1a945a Mon Sep 17 00:00:00 2001
From: Ben Dunbobbin <Ben.Dunbobbin at sony.com>
Date: Fri, 30 Jan 2026 15:31:47 +0000
Subject: [PATCH 6/6] Replace TODOs section with a Limitations section
---
llvm/docs/DTLTO.rst | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/llvm/docs/DTLTO.rst b/llvm/docs/DTLTO.rst
index 443c9e2a137e6..98138cbfcfab5 100644
--- a/llvm/docs/DTLTO.rst
+++ b/llvm/docs/DTLTO.rst
@@ -169,10 +169,10 @@ following backend compilation commands with maximum parallelism:
/usr/bin/clang -O2 -c -fprofile-sample-use=my.prof t2.o -fthinlto-index=t2.o.thinlto.bc -o t2.native.o \
-fproc-stat-report=t2.stats.txt
-TODOs
------
+Limitations
+-----------
-The following features are planned for DTLTO but not yet implemented:
+The following features are not implemented at this time:
- Support for platforms other than ELF and COFF.
- Support for more LTO configurations; only a very limited set of LTO
More information about the llvm-commits
mailing list