<div dir="ltr">Anyone know how to get these changes on <a href="http://clang.llvm.org/docs/">http://clang.llvm.org/docs/</a>? Is that site periodically refreshed or do I need to do something explicit?<div><br></div><div>Thanks,</div><div>Teresa</div></div><div class="gmail_extra"><br><div class="gmail_quote">On Wed, Sep 21, 2016 at 9:57 AM, Teresa Johnson via cfe-commits <span dir="ltr"><<a href="mailto:cfe-commits@lists.llvm.org" target="_blank">cfe-commits@lists.llvm.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Author: tejohnson<br>
Date: Wed Sep 21 11:57:03 2016<br>
New Revision: 282089<br>
<br>
URL: <a href="http://llvm.org/viewvc/llvm-project?rev=282089&view=rev" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-<wbr>project?rev=282089&view=rev</a><br>
Log:<br>
[docs] Add ThinLTO user documentation<br>
<br>
Summary: Add some user facing documentation on ThinLTO and how to use it.<br>
<br>
Reviewers: mehdi_amini<br>
<br>
Subscribers: mehdi_amini, cfe-commits<br>
<br>
Differential Revision: <a href="https://reviews.llvm.org/D24806" rel="noreferrer" target="_blank">https://reviews.llvm.org/<wbr>D24806</a><br>
<br>
Added:<br>
cfe/trunk/docs/ThinLTO.rst<br>
Modified:<br>
cfe/trunk/docs/CommandGuide/<wbr>clang.rst<br>
cfe/trunk/docs/index.rst<br>
<br>
Modified: cfe/trunk/docs/CommandGuide/<wbr>clang.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/CommandGuide/clang.rst?rev=282089&r1=282088&r2=282089&view=diff" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-<wbr>project/cfe/trunk/docs/<wbr>CommandGuide/clang.rst?rev=<wbr>282089&r1=282088&r2=282089&<wbr>view=diff</a><br>
==============================<wbr>==============================<wbr>==================<br>
--- cfe/trunk/docs/CommandGuide/<wbr>clang.rst (original)<br>
+++ cfe/trunk/docs/CommandGuide/<wbr>clang.rst Wed Sep 21 11:57:03 2016<br>
@@ -328,13 +328,19 @@ Code Generation Options<br>
model can be overridden with the tls_model attribute. The compiler will try<br>
to choose a more efficient model if possible.<br>
<br>
-.. option:: -flto, -emit-llvm<br>
+.. option:: -flto[=full,thin], -emit-llvm<br>
<br>
Generate output files in LLVM formats, suitable for link time optimization.<br>
When used with :option:`-S` this generates LLVM intermediate language<br>
assembly files, otherwise this generates LLVM bitcode format object files<br>
(which may be passed to the linker depending on the stage selection options).<br>
<br>
+ The default for :option:`-flto` is :option:`-flto=full`, in which the<br>
+ LLVM bitcode is suitable for monolithic Link Time Optimization (LTO), where<br>
+ the linker merges all such modules into a single combined module for<br>
+ optimization. With :option:`-flto=thin`, :doc:`ThinLTO <../ThinLTO>`<br>
+ compilation is invoked instead.<br>
+<br>
Driver Options<br>
~~~~~~~~~~~~~~<br>
<br>
<br>
Added: cfe/trunk/docs/ThinLTO.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/ThinLTO.rst?rev=282089&view=auto" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-<wbr>project/cfe/trunk/docs/<wbr>ThinLTO.rst?rev=282089&view=<wbr>auto</a><br>
==============================<wbr>==============================<wbr>==================<br>
--- cfe/trunk/docs/ThinLTO.rst (added)<br>
+++ cfe/trunk/docs/ThinLTO.rst Wed Sep 21 11:57:03 2016<br>
@@ -0,0 +1,157 @@<br>
+=======<br>
+ThinLTO<br>
+=======<br>
+<br>
+.. contents::<br>
+ :local:<br>
+<br>
+Introduction<br>
+============<br>
+<br>
+*ThinLTO* compilation is a new type of LTO that is both scalable and<br>
+incremental. *LTO* (Link Time Optimization) achieves better<br>
+runtime performance through whole-program analysis and cross-module<br>
+optimization. However, monolithic LTO implements this by merging all<br>
+input into a single module, which is not scalable<br>
+in time or memory, and also prevents fast incremental compiles.<br>
+<br>
+In ThinLTO mode, as with regular LTO, clang emits LLVM bitcode after the<br>
+compile phase. The ThinLTO bitcode is augmented with a compact summary<br>
+of the module. During the link step, only the summaries are read and<br>
+merged into a combined summary index, which includes an index of function<br>
+locations for later cross-module function importing. Fast and efficient<br>
+whole-program analysis is then performed on the combined summary index.<br>
+<br>
+However, all transformations, including function importing, occur<br>
+later when the modules are optimized in fully parallel backends.<br>
+By default, linkers_ that support ThinLTO are set up to launch<br>
+the ThinLTO backends in threads. So the usage model is not affected<br>
+as the distinction between the fast serial thin link step and the backends<br>
+is transparent to the user.<br>
+<br>
+For more information on the ThinLTO design and current performance,<br>
+see the LLVM blog post `ThinLTO: Scalable and Incremental LTO<br>
+<<a href="http://blog.llvm.org/2016/06/thinlto-scalable-and-incremental-lto.html" rel="noreferrer" target="_blank">http://blog.llvm.org/2016/<wbr>06/thinlto-scalable-and-<wbr>incremental-lto.html</a>>`_.<br>
+While tuning is still in progress, results in the blog post show that<br>
+ThinLTO already performs well compared to LTO, in many cases matching<br>
+the performance improvement.<br>
+<br>
+Current Status<br>
+==============<br>
+<br>
+Clang/LLVM<br>
+----------<br>
+.. _compiler:<br>
+<br>
+The 3.9 release of clang includes ThinLTO support. However, ThinLTO<br>
+is under active development, and new features, improvements and bugfixes<br>
+are being added for the next release. For the latest ThinLTO support,<br>
+`build a recent version of clang and LLVM<br>
+<<a href="http://llvm.org/docs/CMake.html" rel="noreferrer" target="_blank">http://llvm.org/docs/CMake.<wbr>html</a>>`_.<br>
+<br>
+Linkers<br>
+-------<br>
+.. _linkers:<br>
+.. _linker:<br>
+<br>
+ThinLTO is currently supported for the following linkers:<br>
+<br>
+- **gold (via the gold-plugin)**:<br>
+ Similar to monolithic LTO, this requires using<br>
+ a `gold linker configured with plugins enabled<br>
+ <<a href="http://llvm.org/docs/GoldPlugin.html" rel="noreferrer" target="_blank">http://llvm.org/docs/<wbr>GoldPlugin.html</a>>`_.<br>
+- **ld64**:<br>
+ Starting with `Xcode 8 <<a href="https://developer.apple.com/xcode/" rel="noreferrer" target="_blank">https://developer.apple.com/<wbr>xcode/</a>>`_.<br>
+<br>
+Additionally, support is being added to the *lld* linker.<br>
+<br>
+Usage<br>
+=====<br>
+<br>
+Basic<br>
+-----<br>
+<br>
+To utilize ThinLTO, simply add the -flto=thin option to compile and link. E.g.<br>
+<br>
+.. code-block:: console<br>
+<br>
+ % clang -flto=thin -O2 file1.c file2.c -c<br>
+ % clang -flto=thin -O2 file1.o file2.o -o a.out<br>
+<br>
+As mentioned earlier, by default the linkers will launch the ThinLTO backend<br>
+threads in parallel, passing the resulting native object files back to the<br>
+linker for the final native link. As such, the usage model the same as<br>
+non-LTO.<br>
+<br>
+With gold, if you see an error during the link of the form:<br>
+<br>
+.. code-block:: console<br>
+<br>
+ /usr/bin/ld: error: /path/to/clang/bin/../lib/<wbr>LLVMgold.so: could not load plugin library: /path/to/clang/bin/../lib/<wbr>LLVMgold.so: cannot open shared object file: No such file or directory<br>
+<br>
+Then either gold was not configured with plugins enabled, or clang<br>
+was not built with ``-DLLVM_BINUTILS_INCDIR`` set properly. See<br>
+the instructions for the<br>
+`LLVM gold plugin <<a href="http://llvm.org/docs/GoldPlugin.html#how-to-build-it" rel="noreferrer" target="_blank">http://llvm.org/docs/<wbr>GoldPlugin.html#how-to-build-<wbr>it</a>>`_.<br>
+<br>
+Controlling Backend Parallelism<br>
+-----------------------------<wbr>--<br>
+.. _parallelism:<br>
+<br>
+By default, the ThinLTO link step will launch up to<br>
+``std::thread::hardware_<wbr>concurrency`` number of threads in parallel.<br>
+For machines with hyper-threading, this is the total number of<br>
+virtual cores. For some applications and machine configurations this<br>
+may be too aggressive, in which case the amount of parallelism can<br>
+be reduced to ``N`` via:<br>
+<br>
+- gold:<br>
+ ``-Wl,-plugin-opt,jobs=N``<br>
+- ld64:<br>
+ ``-Wl,-mllvm,-threads=N``<br>
+<br>
+Incremental<br>
+-----------<br>
+.. _incremental:<br>
+<br>
+ThinLTO supports fast incremental builds through the use of a cache,<br>
+which currently must be enabled through a linker option.<br>
+<br>
+- gold (as of LLVM r279883):<br>
+ ``-Wl,-plugin-opt,cache-dir=/<wbr>path/to/cache``<br>
+- ld64 (support in clang 3.9 and Xcode 8):<br>
+ ``-Wl,-cache_path_lto,/path/<wbr>to/cache``<br>
+<br>
+Clang Bootstrap<br>
+---------------<br>
+<br>
+To bootstrap clang/LLVM with ThinLTO, follow these steps:<br>
+<br>
+1. The host compiler_ must be a version of clang that supports ThinLTO.<br>
+#. The host linker_ must support ThinLTO (and in the case of gold, must be<br>
+ `configured with plugins enabled <<a href="http://llvm.org/docs/GoldPlugin.html" rel="noreferrer" target="_blank">http://llvm.org/docs/<wbr>GoldPlugin.html</a>>`_.<br>
+#. Use the following additional `CMake variables<br>
+ <<a href="http://llvm.org/docs/CMake.html#options-and-variables" rel="noreferrer" target="_blank">http://llvm.org/docs/CMake.<wbr>html#options-and-variables</a>>`_<br>
+ when configuring the bootstrap compiler build:<br>
+<br>
+ * ``-DLLVM_ENABLE_LTO=Thin``<br>
+ * ``-DLLVM_PARALLEL_LINK_JOBS=1`<wbr>`<br>
+ (since the ThinLTO link invokes parallel backend jobs)<br>
+ * ``-DCMAKE_C_COMPILER=/path/to/<wbr>host/clang``<br>
+ * ``-DCMAKE_CXX_COMPILER=/path/<wbr>to/host/clang++``<br>
+ * ``-DCMAKE_RANLIB=/path/to/<wbr>host/llvm-ranlib``<br>
+ * ``-DCMAKE_AR=/path/to/host/<wbr>llvm-nm``<br>
+<br>
+#. To use additional linker arguments for controlling the backend<br>
+ parallelism_ or enabling incremental_ builds of the bootstrap compiler,<br>
+ after configuring the build, modify the resulting CMakeCache.txt file in the<br>
+ build directory. Specify any additional linker options after<br>
+ ``CMAKE_EXE_LINKER_FLAGS:<wbr>STRING=``. Note the configure may fail if<br>
+ linker plugin options are instead specified directly in the previous step.<br>
+<br>
+More Information<br>
+================<br>
+<br>
+* From LLVM project blog:<br>
+ `ThinLTO: Scalable and Incremental LTO<br>
+ <<a href="http://blog.llvm.org/2016/06/thinlto-scalable-and-incremental-lto.html" rel="noreferrer" target="_blank">http://blog.llvm.org/2016/06/<wbr>thinlto-scalable-and-<wbr>incremental-lto.html</a>>`_<br>
<br>
Modified: cfe/trunk/docs/index.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/index.rst?rev=282089&r1=282088&r2=282089&view=diff" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-<wbr>project/cfe/trunk/docs/index.<wbr>rst?rev=282089&r1=282088&r2=<wbr>282089&view=diff</a><br>
==============================<wbr>==============================<wbr>==================<br>
--- cfe/trunk/docs/index.rst (original)<br>
+++ cfe/trunk/docs/index.rst Wed Sep 21 11:57:03 2016<br>
@@ -37,6 +37,7 @@ Using Clang as a Compiler<br>
SourceBasedCodeCoverage<br>
Modules<br>
MSVCCompatibility<br>
+ ThinLTO<br>
CommandGuide/index<br>
FAQ<br>
<br>
<br>
<br>
______________________________<wbr>_________________<br>
cfe-commits mailing list<br>
<a href="mailto:cfe-commits@lists.llvm.org">cfe-commits@lists.llvm.org</a><br>
<a href="http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits" rel="noreferrer" target="_blank">http://lists.llvm.org/cgi-bin/<wbr>mailman/listinfo/cfe-commits</a><br>
</blockquote></div><br><br clear="all"><div><br></div>-- <br><div class="gmail_signature" data-smartmail="gmail_signature"><span style="font-family:Times;font-size:medium"><table cellspacing="0" cellpadding="0"><tbody><tr style="color:rgb(85,85,85);font-family:sans-serif;font-size:small"><td nowrap style="border-top-style:solid;border-top-color:rgb(213,15,37);border-top-width:2px">Teresa Johnson |</td><td nowrap style="border-top-style:solid;border-top-color:rgb(51,105,232);border-top-width:2px"> Software Engineer |</td><td nowrap style="border-top-style:solid;border-top-color:rgb(0,153,57);border-top-width:2px"> <a href="mailto:tejohnson@google.com" target="_blank">tejohnson@google.com</a> |</td><td nowrap style="border-top-style:solid;border-top-color:rgb(238,178,17);border-top-width:2px"> 408-460-2413</td></tr></tbody></table></span></div>
</div>