fix(linux): Add option to disable GTK signal handler fixup for Delve debugging (#4398) #4808

leaanthony · 2025-12-16T20:48:45Z

Summary

Fixes #4398 - Debug config crashing on Linux when using Delve.

When debugging Wails v3 applications with Delve on Linux, the application crashes at breakpoints. This is caused by Wails' signal handler fixup code (install_signal_handlers()) which adds the SA_ONSTACK flag to various signals (SIGSEGV, SIGBUS, SIGABRT, etc.). While this fixup is necessary for normal CGO/Go signal handling compatibility, it interferes with Delve's debugger.

Changes

Add LinuxOptions.DisableGTKSignalHandlerFixup option to conditionally skip signal handler fixup
Update appNew() to accept the new option parameter
Add documentation for debugging with Delve on Linux
Add option reference documentation

Usage

app := application.New(application.Options{
    Linux: application.LinuxOptions{
        DisableGTKSignalHandlerFixup: true, // Enable for debugging with Delve
    },
})

Files Changed

v3/pkg/application/application_options.go - Added DisableGTKSignalHandlerFixup to LinuxOptions
v3/pkg/application/linux_cgo.go - Conditionally skip install_signal_handlers()
v3/pkg/application/linux_purego.go - Updated function signature for API compatibility
v3/pkg/application/application_linux.go - Pass option to appNew()
v3/UNRELEASED_CHANGELOG.md - Added changelog entry
website/docs/guides/linux.mdx - Added "Debugging with Delve" section
website/docs/reference/options.mdx - Added option documentation

Test plan

Build a Wails v3 app on Linux with DisableGTKSignalHandlerFixup: false (default) - verify normal operation
Build with DisableGTKSignalHandlerFixup: true and debug with Delve - verify breakpoints work
Verify gRPC functionality still works with default settings (signal fixup enabled)

🤖 Generated with Claude Code

Summary by CodeRabbit

Release Notes

New Features
- Added support for Delve debugging on Linux with a new configuration option DisableGTKSignalHandlerFixup that allows developers to control GTK signal handler behavior during debugging sessions and development activities on Linux.
Documentation
- Added comprehensive Linux debugging guide covering Delve debugger integration, detailed configuration instructions, practical code examples, development best practices, and production deployment considerations.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

## Summary I've fixed **GitHub Issue #4398: Debug config crashing on Linux**. ### Root Cause When debugging a Wails v3 application with Delve on Linux, the application crashes at breakpoints. This is caused by Wails' signal handler fixup code (`install_signal_handlers()` in `linux_cgo.go`) which adds the `SA_ONSTACK` flag to various signals. While this fixup is necessary for normal CGO/Go signal handling compatibility (as noted in [golang/go#18255](golang/go#18255)), it interferes with Delve's debugger which relies on specific signal handling behavior. ### The Fix Added a new option `LinuxOptions.DisableGTKSignalHandlerFixup` that allows users to disable the signal handler fixup when debugging: **Files changed:** 1. `v3/pkg/application/application_options.go` - Added `DisableGTKSignalHandlerFixup bool` to `LinuxOptions` 2. `v3/pkg/application/linux_cgo.go` - Modified `appNew()` to conditionally skip `install_signal_handlers()` 3. `v3/pkg/application/linux_purego.go` - Updated `appNew()` signature for API compatibility 4. `v3/pkg/application/application_linux.go` - Pass the new option to `appNew()` 5. `v3/UNRELEASED_CHANGELOG.md` - Added changelog entry ### Usage When debugging with Delve, users should set: ```go app := application.New(application.Options{ Linux: application.LinuxOptions{ DisableGTKSignalHandlerFixup: true, }, // ... other options }) ``` This can be conditionally enabled using build tags or environment variables to only affect debug builds.

All documentation has been added. Here's the complete set of changes: ### Code Changes (already committed in `a4fb64274`): 1. **`v3/pkg/application/application_options.go`** - Added `DisableGTKSignalHandlerFixup bool` to `LinuxOptions` 2. **`v3/pkg/application/linux_cgo.go`** - Modified `appNew()` to conditionally skip `install_signal_handlers()` 3. **`v3/pkg/application/linux_purego.go`** - Updated `appNew()` signature for API compatibility 4. **`v3/pkg/application/application_linux.go`** - Pass the new option to `appNew()` 5. **`v3/UNRELEASED_CHANGELOG.md`** - Added changelog entry ### Documentation Changes (staged, not yet committed): 1. **`website/docs/guides/linux.mdx`** - Added new "Debugging with Delve" section with: - Explanation of the problem - The solution (setting `DisableGTKSignalHandlerFixup: true`) - Build tags pattern for debug vs production builds - Important notes 2. **`website/docs/reference/options.mdx`** - Added documentation for the new `DisableGTKSignalHandlerFixup` option under Linux options Would you like me to commit the documentation changes?

coderabbitai · 2025-12-16T20:49:02Z

Warning

Rate limit exceeded

@leaanthony has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 13 minutes and 6 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between 85c8216 and ba6291d.

📒 Files selected for processing (2)

v3/UNRELEASED_CHANGELOG.md (1 hunks)
v3/pkg/application/linux_cgo.go (1 hunks)

Walkthrough

This change introduces a new Linux debugging option DisableGTKSignalHandlerFixup to resolve GTK signal handler conflicts with Delve debugger. The feature adds a configuration flag that conditionally skips GTK signal handler setup during application initialization, allowing developers to debug Wails applications on Linux without crashes.

Changes

Cohort / File(s)	Summary
Configuration & Options `v3/pkg/application/application_options.go`, `website/docs/reference/options.mdx`	Adds new boolean field `DisableGTKSignalHandlerFixup` to `LinuxOptions` struct with documentation explaining its purpose for Delve debugging compatibility and CGO signal handling.
Platform Implementation `v3/pkg/application/linux_cgo.go`, `v3/pkg/application/linux_purego.go`	Updates `appNew()` function signature across both implementations to accept `disableSignalFixup` parameter; in linux_cgo.go conditionally calls `C.install_signal_handlers()` only when disabled.
Application Initialization `v3/pkg/application/application_linux.go`	Threads the new `DisableGTKSignalHandlerFixup` option through to the `appNew()` call.
Documentation `website/docs/guides/linux.mdx`	Adds new "Debugging with Delve" guide section explaining the GTK signal handler fixup conflict, problem description, and solution with code examples.
Changelog `v3/UNRELEASED_CHANGELOG.md`	Documents the new Linux debugging option addition.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Verify the boolean parameter is correctly threaded from application_linux.go through both linux_cgo.go and linux_purego.go
Confirm conditional logic in linux_cgo.go correctly gates the C.install_signal_handlers() call
Cross-reference documentation consistency across options reference and debugging guide

Suggested labels

Bug, Documentation, go, Linux, v3-alpha, size:M

Suggested reviewers

atterpac

Poem

🐰 A flag for the debuggers so keen,
To hop through the code unseen,
GTK signals no more interfere,
Delve's debugger can venture here,
Fixing the Linux debugging scene! 🔍

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 40.00% which is insufficient. The required threshold is 80.00%.	You can run `@coderabbitai generate docstrings` to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically identifies the main change: adding an option to disable GTK signal handler fixup for Delve debugging on Linux, with the relevant issue reference.
Description check	✅ Passed	The description is comprehensive with clear problem statement, solution, code examples, test plan, and all required files listed. It addresses the template requirements adequately.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

cloudflare-workers-and-pages · 2025-12-16T20:49:46Z

Deploying wails with Cloudflare Pages

Latest commit:	`ba6291d`
Status:	🚫 Build failed.

View logs

sonarqubecloud · 2025-12-17T10:25:00Z

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

leaanthony added 2 commits December 13, 2025 11:27

Merge branch 'v3-alpha' into vk/603e-4398-debug-confi

ba6291d

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

fix(linux): Add option to disable GTK signal handler fixup for Delve debugging (#4398) #4808

fix(linux): Add option to disable GTK signal handler fixup for Delve debugging (#4398) #4808

Uh oh!

leaanthony commented Dec 16, 2025 •

edited by coderabbitai bot

Loading

Uh oh!

coderabbitai bot commented Dec 16, 2025 •

edited

Loading

Rate limit exceeded

Uh oh!

cloudflare-workers-and-pages bot commented Dec 16, 2025 •

edited

Loading

Uh oh!

sonarqubecloud bot commented Dec 17, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

fix(linux): Add option to disable GTK signal handler fixup for Delve debugging (#4398) #4808

Are you sure you want to change the base?

fix(linux): Add option to disable GTK signal handler fixup for Delve debugging (#4398) #4808

Uh oh!

Conversation

leaanthony commented Dec 16, 2025 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Usage

Files Changed

Test plan

Summary by CodeRabbit

Release Notes

Uh oh!

coderabbitai bot commented Dec 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Rate limit exceeded

Walkthrough

Changes

Estimated code review effort

Suggested labels

Suggested reviewers

Poem

Pre-merge checks and finishing touches

Uh oh!

cloudflare-workers-and-pages bot commented Dec 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying wails with Cloudflare Pages

Uh oh!

sonarqubecloud bot commented Dec 17, 2025

Quality Gate passed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

leaanthony commented Dec 16, 2025 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Dec 16, 2025 •

edited

Loading

cloudflare-workers-and-pages bot commented Dec 16, 2025 •

edited

Loading