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

> Understand gdext-nim UpdateMethod options create, overwrite, inject, and disable. Learn how build configuration modifies .gdextension files for efficient Godot development.

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

---

**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`:

```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:

```nim
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`:

```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`.