Function build

python/tvm_ffi/cpp/extension.py:1149–1320

Compile and build a C/C++/CUDA module from source files. This function compiles the given C, C++, and/or CUDA source files into a shared library or object file. The compiler is selected automatically based on file extension: - ``.c`` — compiled with the C compiler (``$CC``) - ``.cc

(  # noqa: PLR0913
    name: str,
    *,
    sources: Sequence[str] | str | None = None,
    cpp_files: Sequence[str] | str | None = None,
    cuda_files: Sequence[str] | str | None = None,
    extra_cflags: Sequence[str] | None = None,
    extra_cuda_cflags: Sequence[str] | None = None,
    extra_ldflags: Sequence[str] | None = None,
    extra_include_paths: Sequence[str] | None = None,
    build_directory: str | None = None,
    backend: str | None = None,
    output: str | None = None,
)

def build(  # noqa: PLR0913
    name: str,
    *,
    sources: Sequence[str] | str | None = None,
    cpp_files: Sequence[str] | str | None = None,
    cuda_files: Sequence[str] | str | None = None,
    extra_cflags: Sequence[str] | None = None,
    extra_cuda_cflags: Sequence[str] | None = None,
    extra_ldflags: Sequence[str] | None = None,
    extra_include_paths: Sequence[str] | None = None,
    build_directory: str | None = None,
    backend: str | None = None,
    output: str | None = None,
) -> str:
    """Compile and build a C/C++/CUDA module from source files.

    This function compiles the given C, C++, and/or CUDA source files into a shared library or
    object file. The compiler is selected automatically based on file extension:

    - ``.c`` — compiled with the C compiler (``$CC``)
    - ``.cc``, ``.cpp``, ``.cxx`` — compiled with the C++ compiler (``$CXX``)
    - ``.o``, ``.obj`` — pre-compiled objects, passed directly to the linker

    When ``output`` is ``None`` (the default) or has a shared-library extension, object files are
    linked into a shared library. When ``output`` has an object-file extension (``.o``, ``.obj``),
    linking is skipped and the path to the object file is returned.

    Note that this function does not automatically export functions to the tvm ffi module. You need to
    manually use the TVM FFI export macros (e.g., ``TVM_FFI_DLL_EXPORT_TYPED_FUNC``) in your source files to export
    functions. This gives you more control over which functions are exported and how they are exported.

    Extra compiler and linker flags can be provided via the ``extra_cflags``, ``extra_cuda_cflags``, and ``extra_ldflags``
    parameters. The default flags are generally sufficient for most use cases, but you may need to provide additional
    flags for your specific use case.

    The include dir of tvm ffi and dlpack are used by default for the compiler to find the headers. Thus, you can
    include any header from tvm ffi in your source files. You can also provide additional include paths via the
    ``extra_include_paths`` parameter and include custom headers in your source code.

    The compiled shared library is cached in a cache directory to avoid recompilation. The `build_directory` parameter
    is provided to specify the build directory. If not specified, a default tvm ffi cache directory will be used.
    The default cache directory can be specified via the `TVM_FFI_CACHE_DIR` environment variable. If not specified,
    the default cache directory is ``~/.cache/tvm-ffi``.

    The C compiler is controlled by the ``$CC`` environment variable (default: ``cc`` on Unix, ``cl`` on Windows).
    The C++ compiler is controlled by the ``$CXX`` environment variable (default: ``c++`` on Unix, ``cl`` on Windows).

    Parameters
    ----------
    name
        The name of the tvm ffi module.
    sources
        Source files to compile. The compiler is auto-detected from the file extension:

        - ``.c`` → C compiler (``$CC``)
        - ``.cc``, ``.cpp``, ``.cxx`` → C++ compiler (``$CXX``)
        - ``.cu`` → CUDA/HIP compiler (``nvcc`` or ``hipcc``)
        - ``.o``, ``.obj`` → pre-compiled objects, passed directly to the linker