# Configuration Options in config.nims for gdext Projects: Complete BuildSettings Guide

> Master your gdext builds with config.nims. Learn how to configure extension metadata, target platforms, and CPU architectures for Godot projects.

- Repository: [godot-nim 4+/gdext-nim](https://github.com/godot-nim/gdext-nim)
- Tags: deep-dive
- Published: 2026-03-02

---

**The `config.nims` file configures gdext builds by importing `gdext/buildconf`, instantiating a `BuildSettings` object, and invoking `configure()` to set extension metadata, target platforms, CPU architectures, and Godot-specific build behaviors.**

The `gdext-nim` repository (godot-nim/gdext-nim) uses NimScript-based configuration to define how Nim extensions compile and link against Godot 4. Every gdext project requires a `config.nims` file that consumes the configuration DSL exposed in `src/gdext/buildconf.nim`, allowing precise control over the generated `.gdextension` file and compilation flags.

## Core Configuration Structure

A valid `config.nims` follows a three-step pattern. First, import the helper module that exposes the configuration DSL. Second, create a `BuildSettings` object with desired fields. Third, pass that object to the `configure` template.

In `src/gdext/buildconf.nim`【https://github.com/godot-nim/gdext-nim/blob/for-4.6-stable/src/gdext/buildconf.nim#L12-L34】, the `BuildSettings` type is defined as a NimScript object containing all build parameters. The `configure` template processes these settings and applies them to the toolchain.

```nim
import gdext/buildconf

let setting = BuildSettings(
  name: "MyExtension",
  target: Target.debug,
)

configure(setting)

```

## BuildSettings Fields Reference

The `BuildSettings` object defines all configurable options for a gdext extension. The following fields control naming, output locations, and build targets:

- **`name`** (`string`): The extension name used for generated file names and the top-level Nim class.
- **`extpath`** (`string`): Path to the `.gdextension` file; if empty, defaults to `projectDir()/name.gdextension`.
- **`entrySymbol`** (`string`, default `"init_library"`): The symbol Godot calls to initialize the library.
- **`genEditorHelp`** (`bool`, default `true`): Controls generation of in-editor class reference files.

### Target Platforms and Architectures

The `platform`, `target`, and `arch` fields define the build matrix:

- **`platform`** (`Platform` enum): Target OS. Valid values include `windows`, `macos`, `linux`, `android`, `ios`, and `web`.
- **`target`** (`Target` enum): Build type—`debug`, `release`, or `editor`.
- **`arch`** (`Architecture` enum): CPU architecture. Options include `default`, `double`, `single`, `x86_32`, `x86_64`, `arm32`, `arm64`, `rv64`, `riscv`, and `wasm32`.

### Update Methods for .gdextension Files

The `updateMethod` field (`UpdateMethod` enum) determines how the generated `.gdextension` file is written:

- **`create`**: Generates a new file if none exists.
- **`overwrite`**: Replaces existing files.
- **`inject`**: Modifies specific sections without overwriting the entire file.
- **`disable`**: Skips `.gdextension` file generation entirely.

### Android-Specific Settings

When targeting Android, two additional fields control the NDK toolchain:

- **`androidNdkVersion`** (`string`, default `"23.2.8568313"`): Version of the Android NDK to use.
- **`androidApiLevel`** (`string`, default `"21"`): Minimum Android API level.

### Internal Configuration

The **`extconfig`** field (`Config` type) holds the parsed `.gdextension` configuration internally. According to the source in `src/gdext/buildconf.nim`, this field is typically left untouched as the `configure` template manages it automatically.

## Global Nim Compiler Options

Beyond the `BuildSettings` object, `config.nims` accepts standard Nim compiler flags. These are processed by the Nim compiler before gdext-specific configuration runs.

For example, the test projects in `testproject/editor/nim/config.nims` and `testproject/runtime/nim/config.nims` use `--path` directives to include source directories outside the current working directory:

```nim
import gdext/buildconf

--path: "src"
--path: "../../../src"

let setting = BuildSettings(
  name: "RuntimeTest",
  genEditorHelp: off,
)

configure(setting)

```

Additionally, the `coronation/config.nims` file demonstrates adding compiler defines:

```nim
--define: ssl

```

## Configuration Examples

### Basic Editor Build

This minimal configuration targets the default platform with editor help enabled:

```nim
import gdext/buildconf

let setting = BuildSettings(
  name: "MyExtension",
  genEditorHelp: on,
)

configure(setting)

```

### Cross-Platform Release Build

Explicitly target Windows 64-bit with release optimizations and no editor help:

```nim
import gdext/buildconf

let setting = BuildSettings(
  name: "MyExtension",
  platform: Platform.windows,
  target: Target.release,
  arch: Architecture.x86_64,
  genEditorHelp: off,
)

configure(setting)

```

### Android Build with Custom NDK

Specify Android ARM64 with a custom API level:

```nim
import gdext/buildconf

let setting = BuildSettings(
  name: "MyExtension",
  platform: Platform.android,
  target: Target.debug,
  arch: Architecture.arm64,
  androidNdkVersion: "23.2.8568313",
  androidApiLevel: "30",
)

configure(setting)

```

## Summary

- **`config.nims`** is a NimScript file that imports `gdext/buildconf` to access the `BuildSettings` DSL.
- **`BuildSettings`** (defined in `src/gdext/buildconf.nim`) controls extension naming, output paths, entry symbols, and target platforms.
- **Target configuration** uses the `Platform`, `Target`, and `Architecture` enums to define OS, build type, and CPU architecture.
- **`.gdextension` management** is handled via `updateMethod` (`create`, `overwrite`, `inject`, `disable`).
- **Android builds** support explicit `androidNdkVersion` and `androidApiLevel` overrides.
- **Global Nim flags** like `--path` and `--define` can be added alongside the `BuildSettings` configuration.

## Frequently Asked Questions

### What is the default entry symbol for gdext libraries?

The default value for `entrySymbol` is `"init_library"`. Godot calls this symbol when loading the shared library. You only need to override this field in `BuildSettings` if your initialization function uses a different name.

### How do I disable editor help generation?

Set `genEditorHelp: off` (or `false`) in your `BuildSettings` object. This is commonly done for release builds or runtime test projects where in-editor documentation is unnecessary, as seen in `testproject/runtime/nim/config.nims`.

### Can I configure multiple target platforms in a single config.nims?

No, a single `config.nims` execution targets one platform/architecture combination. To build for multiple platforms, run the compiler multiple times with different `BuildSettings` configurations, or use conditional logic within the NimScript to switch platforms based on environment variables.

### Where is the BuildSettings type actually defined?

The `BuildSettings` object and `configure` template are declared in `src/gdext/buildconf.nim`【https://github.com/godot-nim/gdext-nim/blob/for-4.6-stable/src/gdext/buildconf.nim#L12-L34】, with internal implementation details referenced in `src/gdext/private/buildsettings.nim`. These files handle the conversion from NimScript configuration to actual compiler flags and `.gdextension` file generation.