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

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.

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:

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:

--define: ssl

Configuration Examples

Basic Editor Build

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

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:

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:

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}