.. meta::
  :description: Tensile is a tool for creating a benchmark-driven backend library for GEMM
  :keywords: Tensile, GEMM, Tensor, Tensile API documentation, Tensile create library

.. _tensilecreatelibrary-cli-reference:

====================
TensileCreateLibrary
====================

``TensileCreateLibrary`` is a command-line tool that generates libraries and code object files for a set of supplied logic files.

Syntax
------

.. code-block::

    TensileCreateLibrary [OPTIONS...] <LOGIC DIRECTORY> <OUTPUT DIRECTORY> <RUNTIME LANGUAGE>

Required arguments
-------------------

Here is the list of required arguments for invoking the ``TensileCreateLibrary`` command.

.. list-table:: Required arguments
  :header-rows: 1

  * - Argument
    - Description

  * - \<LOGIC DIRECTORY\>
    - Absolute path for logic files. The logic files are generally found in either of the following locations:
      |br| \- The build directory under ``3_LibraryLogic``, when generated by the Tensile program. |br|
      |br| \- In a project that hosts pregenerated logic files, such as `rocBLAS <https://github.com/ROCm/rocBLAS/tree/develop/library/src/blas3/Tensile/Logic>`_. |br|

  * - \<OUTPUT DIRECTORY\>
    - Absolute or relative path to the output directory where build artifacts are placed.

  * - \<RUNTIME LANGUAGE\>
    - Runtime language out of OCL, HIP, or HSA

Options
-------

Here is the list of optional arguments for invoking the ``TensileCreateLibrary`` command.

.. list-table:: Options
  :header-rows: 1

  * - Option
    - Description

  * - \-\-architecture=ARCHITECTURE
    - Architectures to generate a library for. When specifying multiple options, use quoted and semicolon-delimited
      architectures such as \-\-architecture='gfx908;gfx1012'.
      Supported architectures include: all; gfx000; gfx803; gfx900; gfx900:xnack-; gfx906; gfx906:xnack+; gfx906:xnack-; gfx908; gfx908:xnack+;
      gfx908:xnack-; gfx90a; gfx90a:xnack+; gfx90a:xnack-; gfx940; gfx940:xnack+; gfx940:xnack-; gfx941; gfx941:xnack+;
      gfx941:xnack-; gfx942; gfx942:xnack+; gfx942:xnack-; gfx1010; gfx1011; gfx1012; gfx1030; gfx1031; gfx1032; gfx1034; gfx1035;
      gfx1100; gfx1101; gfx1102.

  * - \-\-build-client
    - Builds Tensile client executable that is used for stand alone benchmarking. This option is set by default.

  * - \-\-client-config
    - Creates ``best-solution.ini`` in the output directory for the library and generated code object files. This option is set by default.

  * - \-\-code-object-version={default,V4,V5}
    - HSA code object version.

  * - \-\-cxx-compiler={amdclang++, hipcc} or {clang++, hipcc} for Windows
    - C++ compiler used when generating binaries.

  * - \-\-embed-library=EMBEDLIBRARY
    - Specifies the library to embed into static variables.

  * - \-\-embed-library-key=EMBEDLIBRARYKEY
    - Access key for embedding library files.

  * - \-\-generate-manifest-and-exit
    - Similar to the ``dry-run`` option for ``make``, this option computes the outputs
      of ``TensileCreateLibrary`` and writes the expected outputs to a
      manifest file but doesn't exectue the commands to generate the output.

  * - \-\-generate-sources-and-exit
    - Skips building the source and assembly code object files. Outputs source files only and exits.

  * - \-\-ignore-asm-cap-cache
    - Ignores the asm capability cache and derives the asm capabilities at runtime.

  * - \-\-jobs=CPUTHREADS or \-j CPUTHREADS
    - Number of parallel jobs to launch. If this option is supplied with a value higher than ``nproc``, the number of parallel
      jobs will be the same as the number of cores. If this option is supplied with a value below 1 (0 or -1), the number
      of parallel jobs will be the same as the number of cores, up to a maximum of 64. The default value is -1.
  * - \-\-lazy-library-loading
    - Loads Tensile libraries only when needed.

  * - \-\-library-format={yaml,msgpack}
    - Specifies the library format to use. Default value: ``msgpack``.

  * - \-\-no-enumerate
    - Prohibits ``rocm_agent_enumerator`` from running.

  * - \-\-no-merge-files
    - Stores every solution and kernel in separate files.

  * - \-\-no-short-file-names
    - Prohibits short files names.

  * - \-\-num-merged-files=NUMMERGEDFILES
    - Number of files the kernels must be written into.

  * - \-\-merge-files
    - Stores all solutions in a single file. This is set by default.

  * - \-\-short-file-names
    - Converts solution and kernel names to serial Ids if Windows kernel name is too long. The option is set by default.

  * - \-\-separate-architectures
    - Separates ``TensileLibrary`` file according to architecture to reduce the library file loading time.
      This option writes each architecture into a different ``TensileLibrary_gfxXXX.dat`` file.

  * - \-\-verbose=PRINTLEVEL or \-v PRINTLEVEL
    - Sets printout verbosity level out of 0, 1, and 2.

  * - \-\-version=VERSION
    - Version string to embed into the library file.

  * - \-\-write-master-solution-index
    - Outputs master solution index including number
      of kernels per architecture post build in csv format.

Usage without options
-----------------------

Here is how to run ``TensileCreateLibrary`` command without options. The specified logic directory contains the
logic files and the generated artifacts are directed to the *tensile-output* directory that is created in the directory where the ``TensileCreateLibrary``
command is invoked. The runtime language is HIP.

.. code-block::

    TensileCreateLibrary /home/myuser/Logic tensile-output HIP

Usage with options
--------------------

Here is how to run ``TensileCreateLibrary`` command with options. The following example shows options with and without arguments.

.. code-block::

    TensileCreateLibrary --separate-architectures --jobs=32 /home/myuser/Logic tensile-output HIP

.. |br| raw:: html

    <br />
