Skip to content

Add Windows and MacOS configuration section #4662

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Romerolweb wants to merge 3 commits into
base: master
Choose a base branch
from
+50 −0
Open

Add Windows and MacOS configuration section #4662

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ff29334
Add Windows and MacOS configuration section
Romerolweb Oct 23, 2025
b4ccb80
docs: add Windows/MacOS config sections to main docs
leaanthony Jan 25, 2026
e12445f
Merge branch 'master' into patch-1
leaanthony Feb 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions website/docs/guides/ides.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,8 @@ The 2 files generated are `tasks.json` and `launch.json`. Below are the files ge
}
```

### Windows configuration

```json title="launch.json"
{
"version": "0.2.0",
Expand All @@ -64,6 +66,29 @@ The 2 files generated are `tasks.json` and `launch.json`. Below are the files ge
}
```

### MacOS configuration

```json title="launch.json"
{
"version": "0.2.0",
"configurations": [
{
"name": "Wails: Debug myproject (macOS)",
"type": "go",
"request": "launch",
"mode": "exec",
"program": "${workspaceFolder}/build/bin/myproject",
"preLaunchTask": "build",
"cwd": "${workspaceFolder}",
"env": {
"GOOS": "darwin",
"GOARCH": "amd64"
}
}
]
}
```

### Configuring the install and build steps

The `tasks.json` file is simple for the default project as there is no `npm install` or `npm run build` step needed.
Expand Down
25 changes: 25 additions & 0 deletions website/versioned_docs/version-v2.10/guides/ides.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,8 @@ The 2 files generated are `tasks.json` and `launch.json`. Below are the files ge
}
```

### Windows configuration

```json title="launch.json"
{
"version": "0.2.0",
Expand All @@ -64,6 +66,29 @@ The 2 files generated are `tasks.json` and `launch.json`. Below are the files ge
}
```

### MacOS configuration

```json title="launch.json"
{
"version": "0.2.0",
"configurations": [
{
"name": "Wails: Debug myproject (macOS)",
"type": "go",
"request": "launch",
"mode": "exec",
"program": "${workspaceFolder}/build/bin/myproject",
"preLaunchTask": "build",
"cwd": "${workspaceFolder}",
"env": {
"GOOS": "darwin",
"GOARCH": "amd64"
}
Comment on lines +69 to +86
Copy link
Contributor

@coderabbitai coderabbitai bot Jan 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

cat "website/versioned_docs/version-v2.10/guides/ides.mdx" | head -120

Repository: wailsapp/wails

Length of output: 2956

🌐 Web query:

VS Code Go debugger launch.json macOS GOARCH environment variable best practices

💡 Result:

Best practices: GOARCH in VS Code Go debug (launch.json) on macOS

  1. Don’t set GOARCH unless you truly need it.
    For normal local debugging, let Go/Delve use your host defaults (Apple Silicon: darwin/arm64; Intel: darwin/amd64). GOARCH is primarily a build target selector (often paired with GOOS). [2]

  2. If you do set GOARCH, ensure the whole toolchain matches (Go + dlv + the binary).
    Debugging generally assumes the compiled binary matches the architecture Delve is running under. Practically:

    • Apple Silicon: prefer GOARCH=arm64 and an arm64 dlv.
    • If you need to debug an x86_64 (amd64) build on Apple Silicon, use a consistent x86_64 toolchain (often meaning running the relevant tools under Rosetta and using an amd64 dlv). (Mixing arch is a common cause of “breakpoints don’t hit / weird debugger behavior”.)

  3. Use env / envFile correctly: they apply to the debuggee process environment.
    In launch.json, env defines environment variables passed to the launched program, and it merges with envFile (and go.toolsEnvVars) with precedence env > envFile > go.toolsEnvVars. [1]

  4. If you need a different GOARCH only for the build, build in a preLaunchTask and debug with "mode": "exec"—don’t rely on launch.json env to affect the build step.
    The VS Code Go docs explicitly note that settings like env in launch.json apply to running the compiled binary, not building it—so put build env/flags in the task. [3]

Example: build amd64 binary via task, then debug it (recommended pattern)

.vscode/tasks.json

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "go: build (debug, amd64)",
      "type": "shell",
      "command": "go",
      "args": ["build", "-gcflags=all=-N -l", "-o", "${workspaceFolder}/__debug_bin_amd64", "./cmd/myapp"],
      "options": {
        "env": { "GOARCH": "amd64" }
      }
    }
  ]
}

.vscode/launch.json

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug exec (amd64 build)",
      "type": "go",
      "request": "launch",
      "mode": "exec",
      "program": "${workspaceFolder}/__debug_bin_amd64",
      "preLaunchTask": "go: build (debug, amd64)"
    }
  ]
}

Sources: VS Code Go debug config env/envFile behavior [1]; what GOARCH does for builds [2]; why build env should live in the pre-launch task (launch env doesn’t apply to building) [3].

macOS launch config is inconsistent with the shown build task and hardcodes incompatible GOARCH.

The generic tasks.json builds to build/bin/myproject.exe, but the macOS launch.json targets build/bin/myproject (no .exe), causing a mismatch. Additionally, hardcoding GOARCH: "amd64" fails on Apple Silicon (arm64 hosts). If GOARCH must differ for builds, it belongs in the task's options.env, not in launch.json (where env only affects the debuggee process, not the build). For local debugging on macOS, omit GOARCH entirely to use the host default, or conditionally set it based on the actual machine architecture.

💡 Proposed doc fix (align macOS config with proper build/arch handling) 
 ### MacOS configuration
 
+Before using this configuration on macOS, ensure your build task outputs to `build/bin/myproject` (without `.exe`),
+and remove the hardcoded `GOARCH: "amd64"` to use your machine's native architecture (arm64 for Apple Silicon, amd64 for Intel).
+Alternatively, if a specific `GOARCH` is needed, define it in your `tasks.json` build command instead of `launch.json`.
+
 ```json title="launch.json"
 {
     "version": "0.2.0",
🤖 Prompt for AI Agents 
In `@website/versioned_docs/version-v2.10/guides/ides.mdx` around lines 69 - 86,
The macOS launch.json is inconsistent with the build task and hardcodes an
incompatible GOARCH; update launch.json so its "program" matches the binary
produced by the build task (the same path used in tasks.json) and remove the
hardcoded "env": { "GOARCH": "amd64" } from launch.json (env in launch.json only
affects the debuggee, not the build). If you need to control GOARCH for
cross-building, move that setting into the build task's options.env in
tasks.json (or omit it entirely to use the host architecture), and ensure
"preLaunchTask": "build" produces the same output filename referenced by
"program".

}
]
}
```

### Configuring the install and build steps

The `tasks.json` file is simple for the default project as there is no `npm install` or `npm run build` step needed.
Expand Down