How to Configure Debug, Release, and Editor Build Targets with gdextwiz

Use the -d:target= flag (e.g., -d:target=release or -d:target=editor) when running gdextwiz build to override the default debug configuration and generate optimized or editor-specific binaries.

The gdextwiz command-line tool is the official build orchestrator for the gdext-nim framework, which enables Nim-based GDExtension development for Godot 4. Configuring different build targets ensures your extension ships with appropriate optimizations for development, production, or editor-specific workflows.

Understanding the Target Enum and Default Behavior

In src/gdext/buildconf.nim (lines 90–95), the build system defines three distinct targets via the Target enum:

type Target* = enum
  debug   ## Target with debug symbols

  release ## Optimized build without debug symbols

  editor  ## Editor build

The system determines which target to use through the defaultTarget proc (lines 79–87 in src/gdext/buildconf.nim). By default, if no target is specified via the command line, the system builds for debug unless the Nim compiler was already invoked with -d:release.

When you explicitly pass -d:target=release or -d:target=editor, the cmdswitched(Target) check detects the override and converts the string value to the corresponding enum member via cmddefTarget.toTarget.

How gdextwiz Forwards Configuration to the Compiler

The gdextwiz binary acts as a thin wrapper that collects raw arguments and forwards them to the Nim compiler. In src/gdext/gdextwiz.nim (lines 70–89), the tool parses sub-commands and options using parseopt.

When you run gdextwiz build, the call chain proceeds through dispatch_build to dispatch_iteration in src/gdext/wizard/subcommands/iteration.nim (lines 100–104). Here, the iteration dispatcher collects every argument starting with -d: into a nimargs sequence:

proc dispatch_iteration(opt: var OptParser; command: Command) =
  # ...

  of cmdShortOption, cmdLongOption:
    nimargs.add opt.reverseOpt   # keeps every –d:… option

  # ...

  quit command(nimargs, search_path, depth)

Source: src/gdext/wizard/subcommands/iteration.nim lines 85–96

These accumulated switches are then passed to the build routine, which instantiates a BuildSettings record and calls configure. If the resolved target is release, the configuration injects an additional compiler hint:

if setting.target == release:
  defineHint("release")

Source: src/gdext/buildconf.nim lines 60–62

This mechanism ensures the Nim compiler receives the correct set of defines to optimize (or debug) your GDExtension binary.

Step-by-Step Build Target Configuration

Debug Builds (Default)

Running gdextwiz build without additional flags produces a debug binary with full symbols. This is equivalent to explicitly requesting the debug target:

gdextwiz build

# Equivalent to:

gdextwiz build -d:target=debug

The resulting library filename will contain .debug. (for example, libMyExtension.linux.debug.x86_64.so), and the .gdextension file will map to the linux.debug library entry.

Release Builds

To ship optimized code without debug symbols, pass the release target flag. This triggers the defineHint("release") injection and produces an optimized binary:

gdextwiz build -d:target=release

The output filename will include .release. (for example, libMyExtension.linux.release.x86_64.so). The defaultTarget proc explicitly checks for this flag in src/gdext/buildconf.nim (lines 79–87) to bypass the default debug selection.

Editor Builds

When developing tools that must run inside the Godot Editor itself (rather than in an exported game), use the editor target:

gdextwiz build -d:target=editor

This generates a binary with the .editor. suffix and ensures compatibility with the editor's specific API requirements. The editor variant is distinct from both debug and release because it may link against editor-specific Godot symbols.

Combining Targets with Platform-Specific Flags

You can chain the target flag with other defines supported by gdext-nim. For example, to build a WebAssembly release binary:

gdextwiz build -d:target=release -d:platform=web -d:arch=wasm32 path/to/project

The dispatch_iteration proc preserves all -d: arguments in order, passing them directly to the Nim compiler that ultimately builds bootstrap.nim with your specified configuration.

Summary

• Three targets exist: debug (default), release (optimized), and editor (for Godot Editor plugins), defined in src/gdext/buildconf.nim.
• Override via CLI: Pass -d:target=release or -d:target=editor to gdextwiz build to change the build mode.
• Forwarding mechanism: gdextwiz collects all -d: switches in dispatch_iteration (src/gdext/wizard/subcommands/iteration.nim) and passes them to the Nim compiler.
• Compiler hints: When targeting release, the configure proc automatically injects defineHint("release") to signal downstream code.
• Output naming: The target name appears in the generated library filename (e.g., .linux.release.x86_64.so) and in the .gdextension library mappings.

Frequently Asked Questions

How do I verify which target gdextwiz is actually building?

Inspect the generated binary filename in your output directory; it will contain .debug., .release., or .editor. based on the active target. You can also check the libraries section of your .gdextension file, which contains keys like linux.release or linux.debug mapping to the specific binaries.

What is the difference between -d:release and -d:target=release?

While both may trigger release builds, -d:target=release is the explicit, preferred method for gdext-nim. It sets the Target enum value in buildconf.nim (lines 79–87) and ensures the build system correctly names the output file and sets all internal compiler hints. Using -d:release alone relies on Nim's built-in define and may not trigger gdext-nim-specific release configurations.

Can I build for the editor and release simultaneously in one command?

No, a single gdextwiz build invocation targets one specific configuration. To generate both binaries, run the command twice with different target flags, then reference both outputs in your .gdextension file under separate library keys (e.g., linux.editor and linux.release).

Why does my editor build fail when my debug build succeeds?

The editor target links against Godot Editor-specific APIs that are stripped from export templates. If your code references editor-only classes or functions, it will compile successfully only when -d:target=editor is set, but fail for debug or release targets intended for exported games.

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