# Build and link an application

An application using Libnative is built with a **native** host compiler, not
hexagon-clang. Libnative is meant to be built for x86 or ARM, so upstream clang++,
g++, etc. is required. hexagon-clang is reserved for the Hexagon target and should
not be used simultaneously with Libnative.

A C++ compiler is required.

## Installation layout

Libnative is packaged as a part of the normal Hexagon toolchain release,
and is slightly present under `Tools/libnative`. The exact shape of the library
varies based on host architecture.

| Directory | Contents |
| --- | --- |
| `linux-x86_64` | `libnative.a`, headers, `defaults.toml`. |
| `linux-aarch64` | `libnative.a`, headers, `defaults.toml`. |
| `windows-x86_64` | `libnative.dll`, `libnative.lib`, headers,<br>`defaults.toml`. |
| `windows-aarch64` | `libnative.dll`, `libnative.lib`, headers,<br>`defaults.toml`. |

Libnative is provided as a static library on Linux and as a shared object on
Windows. Headers and `share/` are duplicated per platform. `share/` holds a
reference copy of `defaults.toml`; see [Default configuration reference](https://docs.qualcomm.com/doc/80-N3040-23/topic/libnative-ug-configuration.html#libnative-config-defaults).

On Linux, you may choose to yourself link the static library as a shared object.
This is not required for general use. Please ensure you are not linking multiple
instances of Libnative simultaneously, as errors may arise.

## Public headers

| Header | Language | Provides |
| --- | --- | --- |
| `hexagon_protos.h` | C++ only | Scalar intrinsic definitions. Includes the extension headers and<br>`udma.h`, so including it alone is sufficient. Aligns with<br>hexagon-clang. |
| `hvx_hexagon_protos.h` | C++ only | HVX intrinsic definitions. |
| `hmx_hexagon_protos.h` | C++ only | HMX intrinsic definitions. |
| `hexagon_types.h` | C++ only | Type definitions for Hexagon. |
| `udma.h` | C and C++ | Type definitions for UDMA. Required by the DMA intrinsics, which take a<br>`void*` pointing at one of its descriptor structs. |
| `libnative_config.h` | C and C++ | Function definitions for configuring Libnative.<br>`libnative_configure()` and other utility functions are here. |
| `c_hexagon_protos.h` | C and C++ | **Deprecated** C compatibility layer, to be removed in Libnative 25.0.<br>See [Build C sources as C++](https://docs.qualcomm.com/doc/80-N3040-23/topic/libnative-ug-migration.html#libnative-c-compatibility). |

As of 23.0 the intrinsic headers are C++ headers only. `hexagon_types.h` is
likewise C++-only by design: it defines the Hexagon types using C++ constructs.
This is intentional and not a portability gap – the C-includable surface is
`c_hexagon_protos.h`, which supplies its own layout-compatible type
definitions when compiled as C.

Only `udma.h`, `libnative_config.h`, and `c_hexagon_protos.h` can be
included from a C translation unit.

## Compile and link

Add the include directory to the include path, the platform library directory
to the library search path, and link the library using `-lnative`. On Linux,
the math library is also required. The link options must follow all source files
when invoked on the command line.

Linux, static archive:

clang++ -Ipath/to/Tools/libnative/include foo.cpp \
        -Lpath/to/Tools/libnative/lib -lnative -lm
    Copy to clipboard

## Confirm which library you have

Build information is embedded into the library at build time and exposed through
two entry points:

const char* libnative_version_json(void);  /* returns a JSON string */
    void        libnative_dump_version(void);  /* prints to stdout */
    Copy to clipboard

The blob records the source revision, whether the tree was modified, and the
full architecture manifest. This information should be provided for debugging.

Last Published: Oct 06, 2026

[Previous Topic
Stop selecting the architecture by tools release](https://docs.qualcomm.com/bundle/publicresource/80-N3040-23/topics/libnative-ug-migration.md) [Next Topic
Configuration](https://docs.qualcomm.com/bundle/publicresource/80-N3040-23/topics/libnative-ug-configuration.md)