UpdateMethod Options in gdext-nim Build Configuration: create, overwrite, inject, and disable Explained

The UpdateMethod enum in gdext-nim controls how the build system modifies the .gdextension configuration file, offering four strategies ranging from complete file recreation to read-only access.

When building Godot extensions with Nim using the godot-nim/gdext-nim framework, the build system must synchronize build artifacts with the .gdextension configuration file that Godot uses to load native libraries. The UpdateMethod setting in your build configuration determines exactly how aggressively the system modifies this file—whether it creates fresh configurations, overwrites existing values, injects missing keys, or disables file modifications entirely.

What is UpdateMethod in gdext-nim?

According to the godot-nim/gdext-nim source code, UpdateMethod is an enum defined in src/gdext/buildconf.nim (lines 109–115) that specifies the file update strategy during the configure phase of the build. When you run a build, the system generates or modifies the .gdextension file to reflect current library paths, entry points, and dependencies. The UpdateMethod you select dictates whether the build system preserves manual edits, forces complete replacement, or skips disk writes altogether.

The Four UpdateMethod Options Explained

create

create starts with an empty configuration object and writes every section and key from scratch. This is the default value (setting.updateMethod = create) and is ideal for fresh extensions or when you want to guarantee a clean, predictable configuration file without legacy entries.

overwrite

overwrite loads the existing .gdextension file and replaces any matching keys with new values while preserving the file’s overall structure. Use this when you need to update specific fields—such as changing the library binary name or version—without deleting manually added sections that your build system does not manage.

inject

inject loads the existing file and adds only missing keys, leaving all existing values untouched. This is the safest option when you have manually edited the .gdextension file and want to ensure required keys exist without overwriting your customizations. The system checks hasKeyOrPut to avoid modifying existing entries.

disable

disable loads the existing configuration for side-effects—such as determining output paths for the DLL—but explicitly skips writing any changes back to disk. According to the source in src/gdext/buildconf.nim (lines 84–88), the writeConfig call is discarded when this method is active, making it perfect for CI pipelines or testing where you want to build the library without altering the checked-in configuration.

How UpdateMethod Works Under the Hood

The actual update logic resides in the update procedure at lines 62–66 of src/gdext/buildconf.nim:

proc update(section: Section; updateMethod: UpdateMethod; key, value: string) =
  case updateMethod
  of create, overwrite: `[]=`(section, key, value)          # write/replace

  of inject, disable: discard hasKeyOrPut(section, key, value) # add‑if‑missing

During the build process, the configure procedure invokes fillupMissingRequirements (lines 68–79), which iterates over required sections like configuration and libraries, calling update for each key. The persistence logic then branches based on your selected method:

case setting.updateMethod
of create, overwrite, inject:
  writeConfig(setting.extconfig, setting.extpath)  # persist changes

of disable:
  discard                                         # no write

This architecture allows inject and disable to share the same "add-if-missing" logic during the in-memory phase, while diverging at the final write step—inject persists the merged result, whereas disable discards it.

Practical Configuration Examples

The following examples demonstrate how to configure each UpdateMethod using the BuildSettings object exposed via src/gdext/gdextwiz.nim:

import gdext/gdextwiz

# 1. Create a fresh .gdextension file (default behavior)

var cfgCreate = BuildSettings(
  name: "MyExtension",
  updateMethod: UpdateMethod.create
)
configure(cfgCreate)  # Completely replaces any existing file

# 2. Overwrite specific entries while preserving manual sections

var cfgOverwrite = BuildSettings(
  name: "MyExtension",
  updateMethod: UpdateMethod.overwrite
)
configure(cfgOverwrite)  # Updates library paths but keeps custom metadata

# 3. Inject missing keys only (preserve manual edits)

var cfgInject = BuildSettings(
  name: "MyExtension",
  updateMethod: UpdateMethod.inject
)
configure(cfgInject)  # Adds missing entries without touching existing values

# 4. Disable writing – build DLL but never touch the config file

var cfgDisable = BuildSettings(
  name: "MyExtension",
  updateMethod: UpdateMethod.disable
)
configure(cfgDisable)  # Generates extension binary; .gdextension remains unchanged

Summary

• create generates a brand-new .gdextension file, overwriting any existing content (default behavior).
• overwrite merges new values into an existing file, replacing matching keys while preserving un managed sections.
• inject adds only missing required keys, ensuring manual edits remain intact.
• disable reads the configuration for build context but never writes modifications to disk.

Frequently Asked Questions

What is the default UpdateMethod in gdext-nim?

UpdateMethod.create is the default setting. When you instantiate BuildSettings without explicitly setting updateMethod, the system defaults to create, which generates a fresh .gdextension file from scratch during the configure phase.

Which UpdateMethod preserves manual edits in my .gdextension file?

Use UpdateMethod.inject to preserve manual edits. This option uses hasKeyOrPut logic to add only missing keys, ensuring that any custom sections or values you added manually remain untouched while the build system guarantees required fields exist.

Does UpdateMethod.disable prevent the DLL from being built?

No, disable only stops the configuration file write. The build system still processes the configuration to determine output paths and builds the shared library (DLL). It simply discards the final writeConfig call, leaving the .gdextension file on disk unchanged.

Where is the UpdateMethod enum defined in the source code?

The enum is defined in src/gdext/buildconf.nim at lines 109–115. The related update logic resides in the same file at lines 62–66 (the update procedure) and lines 84–88 (the persistence logic), with configuration helpers available in src/gdext/private/configdsl.nim.

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