llvm-project/clang/docs/ClangNvlinkWrapper.rst

====================
Clang Nvlink Wrapper
====================

.. contents::
   :local:

.. _clang-nvlink-wrapper:

Introduction
============

This tool works as a wrapper over the ``nvlink`` program. It is required
because ``nvlink`` does not support linking of archive files implicitly. It
transparently passes every input option and object to ``nvlink`` except archive
files. It reads each input archive file to extract the archived cubin files as
temporary files. These temporary (*.cubin) files are passed to ``nvlink``.

Use Case
========

During linking of heterogeneous device archive libraries with an OpenMP
program, the :doc:`ClangOffloadBundler` creates a device specific archive of
cubin files. Such an archive is then passed to this wrapper tool to extract
cubin files before passing to ``nvlink``.

Working
=======

**Inputs**

  A command line generated by the OpenMP-Clang driver targeting NVPTX,
  containing a set of flags, cubin object files, and zero or more archive
  files.

Example::

  clang-nvlink-wrapper main.cubin /tmp/libTest-nvptx-sm_50.a -o main-linked.out

**Processing**

  1. From each archive file extract all cubin files as temporary files and
     store their names in a list, `CubinFiles`.
  2. Create a new command line, `NVLinkCommand`, such that
     * Program is ``nvlink``
     * All input flags are transparently passed on as flags
     * All input archive file are replaced with `CubinFiles`
  3. Execute NVLinkCommand

::

  1. Extract (libTest-nvptx-sm_50.a) => /tmp/a.cubin /tmp/b.cubin
  2. nvlink -o a.out-openmp-nvptx64 main.cubin /tmp/a.cubin /tmp/b.cubin
  
**Output**

  Output file generated by ``nvlink`` which links all cubin files.