* doc/invoke.texi (-flinker-output): Document

From-SVN: r260965

gcc/ChangeLog

 2018-05-30  Jan Hubicka  <hubicka@ucw.cz>
 
+	* doc/invoke.texi (-flinker-output): Document
+
+2018-05-30  Jan Hubicka  <hubicka@ucw.cz>
+
 	* passes.c (ipa_write_summaries): Only modify statements if body
 	is in memory.
 	* cgraphunit.c (ipa_passes): Also produce intermeidate code when

gcc/doc/invoke.texi

@@ -12294,6 +12294,50 @@ If any of these options is used, then the linker is not run, and
 object file names should not be used as arguments.  @xref{Overall
 Options}.
 
+@item -flinker-output=@var{type}
+@opindex -flinker-output
+This option controls the code generation of the link time optimizer.  By
+default the linker output is determined by the linker plugin automatically. For
+debugging the compiler and in the case of incremental linking to non-lto object
+file is desired, it may be useful to control the type manually.
+
+If @var{type} is @samp{exec} the code generation is configured to produce static
+binary. In this case @option{-fpic} and @option{-fpie} are both disabled.
+
+If @var{type} is @samp{dyn} the code generation is configured to produce shared
+library. In this case @option{-fpic} or @option{-fPIC} is preserved, but not
+enabled automatically.  This makes it possible to build shared libraries without
+position independent code on architectures this is possible, i.e. on x86.
+
+If @var{type} is @samp{pie} the code generation is configured to produce
+@option{-fpie} executable. This result in similar optimizations as @samp{exec}
+except that @option{-fpie} is not disabled if specified at compilation time.
+
+If @var{type} is @samp{rel} the compiler assumes that incremental linking is
+done.  The sections containing intermediate code for link-time optimization are
+merged, pre-optimized, and output to the resulting object file. In addition, if
+@option{-ffat-lto-objects} is specified the binary code is produced for future
+non-lto linking. The object file produced by incremental linking will be smaller
+than a static library produced from the same object files.  At link-time the
+result of incremental linking will also load faster to compiler than a static
+library assuming that majority of objects in the library are used.
+
+Finally @samp{nolto-rel} configure compiler to for incremental linking where
+code generation is forced, final binary is produced and the intermediate code
+for later link-time optimization is stripped. When multiple object files are
+linked together the resulting code will be optimized better than with link time
+optimizations disabled (for example, the cross-module inlining will happen),
+most of benefits of whole program optimizations are however lost. 
+
+During the incremental link (by @option{-r}) the linker plugin will default to
+@option{rel}. With current interfaces to GNU Binutils it is however not
+possible to link incrementally LTO objects and non-LTO objects into a single
+mixed object file.  In the case any of object files in incremental link can not
+be used for link-time optimization the linker plugin will output warning and
+use @samp{nolto-rel}. To maintain the whole program optimization it is
+recommended to link such objects into static library instead. Alternatively it
+is possible to use H.J. Lu's binutils with support for mixed objects.
+
 @item -fuse-ld=bfd
 @opindex fuse-ld=bfd
 Use the @command{bfd} linker instead of the default linker.