---
description: "The related code/working directory of this example resides in directory {WAMR_DIR}/samples/custom-section"
---

# The "custom-section" sample project

This sample demonstrates how to:

- embed a separate binary payload into a Wasm custom section through a `.s` file
- load that Wasm module with `WAMR_BUILD_LOAD_CUSTOM_SECTION=1`
- export native APIs that resolve a custom section name to a host-side handle
- print the custom section bytes later through a second native API
- optionally compile the Wasm module to AoT while preserving the `demo` custom section

The Wasm application is built from:

- `wasm-apps/custom_section.c`
- `wasm-apps/custom_section_payload.s`
- `wasm-apps/custom_section_payload.bin`

The assembler file emits a section named `.custom_section.demo`, which becomes a Wasm custom section named `demo` in the final `.wasm` file.

## Why use a custom section for this payload

The payload in this sample is treated as read-only metadata. Putting it in a custom section lets the embedder access the bytes directly from the loaded module through `wasm_runtime_get_custom_section`, instead of copying the data into Wasm linear memory per instance.

That matters when the data is large or rarely changed:

- the bytes stay in the module image as immutable data
- the host can look them up by section name and use them in place
- the Wasm app only needs to pass a small section name and receive a small handle
- no extra application-level serialization or buffer duplication is needed for the read-only payload

This pattern is useful for embedded assets, lookup tables, model metadata, certificates, and other static blobs that the host wants to consume without treating them as mutable Wasm heap data.

## Build this sample

Execute the `build.sh` script. The host executable and the Wasm app are generated in `out`.

```sh
./build.sh
```

Build the AoT variant only when needed by passing `--aot`. This preserves the `demo` custom section in the generated AoT file by calling `wamrc --emit-custom-sections=demo`.

```sh
./build.sh --aot
```

## Run the sample

Enter the output directory and run the Wasm sample directly:

```sh
cd ./out/
./custom_section -f wasm-apps/custom_section.wasm
```

Or run the helper script from `samples/custom_section`:

```sh
./run.sh
```

To run the AoT artifact instead, pass `--aot` to the helper script:

```sh
./run.sh --aot
```