clang/docs/ClangLinkerWrapper.rst

   1 ====================
   2 Clang Linker Wrapper
   3 ====================
   4
   5 .. contents::
   6    :local:
   7
   8 .. _clang-linker-wrapper:
   9
  10 Introduction
  11 ============
  12
  13 This tool works as a wrapper of the normal host linking job. This tool is used
  14 to create linked device images for offloading and the necessary runtime calls to
  15 register them. It works by first scanning the linker's input for embedded device
  16 offloading data stored at the ``.llvm.offloading`` section. This section
  17 contains binary data created by the :doc:`ClangOffloadPackager`. The extracted
  18 device files will then be linked. The linked modules will then be wrapped into a
  19 new object file containing the code necessary to register it with the offloading
  20 runtime.
  21
  22 Usage
  23 =====
  24
  25 This tool can be used with the following options. Any arguments not intended
  26 only for the linker wrapper will be forwarded to the wrapped linker job.
  27
  28 .. code-block:: console
  29
  30   USAGE: clang-linker-wrapper [options] -- <options to passed to the linker>
  31
  32   OPTIONS:
  33     --bitcode-library=<kind>-<triple>-<arch>=<path>
  34                            Extra bitcode library to link
  35     --cuda-path=<dir>      Set the system CUDA path
  36     --device-debug         Use debugging
  37     --device-linker=<value> or <triple>=<value>
  38                            Arguments to pass to the device linker invocation
  39     --dry-run              Print program arguments without running
  40     --embed-bitcode        Embed linked bitcode in the module
  41     --help-hidden          Display all available options
  42     --help                 Display available options (--help-hidden for more)
  43     --host-triple=<triple> Triple to use for the host compilation
  44     --linker-path=<path>   The linker executable to invoke
  45     -L <dir>               Add <dir> to the library search path
  46     -l <libname>           Search for library <libname>
  47     --opt-level=<O0, O1, O2, or O3>
  48                            Optimization level for LTO
  49     -o <path>              Path to file to write output
  50     --pass-remarks-analysis=<value>
  51                            Pass remarks for LTO
  52     --pass-remarks-missed=<value>
  53                            Pass remarks for LTO
  54     --pass-remarks=<value> Pass remarks for LTO
  55     --print-wrapped-module Print the wrapped module's IR for testing
  56     --ptxas-arg=<value>    Argument to pass to the 'ptxas' invocation
  57     --save-temps           Save intermediate results
  58     --sysroot<value>       Set the system root
  59     --verbose              Verbose output from tools
  60     --v                    Display the version number and exit
  61     --                     The separator for the wrapped linker arguments
  62
  63
  64 Example
  65 =======
  66
  67 This tool links object files with offloading images embedded within it using the
  68 ``-fembed-offload-object`` flag in Clang. Given an input file containing the
  69 magic section we can pass it to this tool to extract the data contained at that
  70 section and run a device linking job on it.
  71
  72 .. code-block:: console
  73
  74   clang-linker-wrapper --host-triple=x86_64 --linker-path=/usr/bin/ld -- <Args>