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

> Easily configure debug, release, and editor build targets with gdextwiz using the -d:target flag. Generate optimized or editor-specific binaries for your Godot-Nim projects. Learn how to customize your builds efficiently.

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

---

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

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

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

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

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

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

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

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