v0.3.0 d226234

quickstart.md RawHistoryFolder

Quickstart: WebKitGTK 6.0 Migration

Prerequisites

System Requirements

# Check GTK4 installation
pkg-config --modversion gtk4  # Should be >= 4.0

# Check WebKitGTK 6.0
pkg-config --modversion webkitgtk-6.0  # Should be >= 2.40

# Check Vulkan support (optional but recommended)
vulkaninfo | grep "Vulkan Instance Version"

Install Dependencies (Arch Linux)

sudo pacman -S webkit2gtk-6.0 gtk4 vulkan-tools

Install Dependencies (Ubuntu/Debian)

sudo apt install libwebkitgtk-6.0-dev libgtk-4-dev vulkan-tools

Build and Test

1. Switch to Feature Branch

git checkout 004-migrate-to-webkitgtk

2. Build the Browser

make clean
make build

3. Verify GPU Rendering

Test Auto-Detection (Default)

# Should auto-detect GPU availability
./dumber browse https://webglsamples.org/aquarium/aquarium.html

Force GPU Mode

# Force GPU acceleration
./dumber browse --rendering-mode=gpu https://webglsamples.org/aquarium/aquarium.html

# Or using environment variable
DUMBER_RENDERING_MODE=gpu ./dumber browse https://example.com

Force CPU Mode

# Force software rendering
./dumber browse --rendering-mode=cpu https://example.com

# Or shorthand
./dumber browse --disable-gpu https://example.com

Debug GPU Compositing

# Show GPU layer borders
./dumber browse --debug-gpu https://example.com

4. Check Rendering Status

# While browser is running, check status
curl http://localhost:8080/api/rendering/status

Expected response:

{
  "mode": "auto",
  "gpu_active": true,
  "gpu_available": true,
  "vulkan_enabled": true,
  "errors": [],
  "performance": {
    "fps": 60,
    "cpu_usage_percent": 15.2,
    "gpu_usage_percent": 45.8,
    "memory_mb": 256
  }
}

Performance Testing

1. Benchmark Page Load

# Measure with GPU
time ./dumber browse --rendering-mode=gpu https://browserbench.org/MotionMark/

# Measure with CPU
time ./dumber browse --rendering-mode=cpu https://browserbench.org/MotionMark/

2. Monitor Resource Usage

# In another terminal, monitor GPU
nvidia-smi -l 1  # For NVIDIA
radeontop        # For AMD

# Monitor CPU
htop

3. Test WebGL Performance

# High-demand WebGL test
./dumber browse https://webglsamples.org/dynamic-cubemap/dynamic-cubemap.html

# Check FPS counter in browser

Troubleshooting

GPU Not Detected

# Check Vulkan drivers
vulkaninfo

# Check OpenGL
glxinfo | grep "OpenGL renderer"

# Force CPU mode if GPU issues
./dumber browse --disable-gpu

Performance Issues

# Enable debug indicators
./dumber browse --debug-gpu https://example.com

# Check for compositing issues (red borders = repaints)

Build Errors

# Ensure correct pkg-config
pkg-config --libs webkitgtk-6.0 gtk4

# Clean and rebuild
make clean
make build

Validation Checklist

  • Browser builds successfully with WebKitGTK 6.0
  • Browser starts in < 500ms
  • GPU acceleration activates when available
  • CPU fallback works when GPU unavailable
  • WebGL content renders correctly
  • No visual artifacts or rendering issues
  • History and bookmarks preserved
  • All existing features work
  • Performance improved with GPU enabled
  • Resource usage within acceptable limits

Migration Verification

Check API Usage

# Verify new GTK4/WebKit6 symbols
ldd ./dumber | grep -E "(gtk-4|webkit.*6)"

# Should see:
# libgtk-4.so.1
# libwebkitgtk-6.0.so.4

Test Key Features

  1. Navigation: URLs load correctly
  2. History: Previous data accessible
  3. Zoom: Ctrl+Plus/Minus works
  4. DevTools: F12 opens inspector
  5. Dmenu: Integration still works

Report Issues

If you encounter issues:

  1. Note the rendering mode used
  2. Check /tmp/dumber.log for errors
  3. Run with --debug-gpu for visual debugging
  4. Report with output of vulkaninfo and glxinfo
source
1# Quickstart: WebKitGTK 6.0 Migration
2
3## Prerequisites
4
5### System Requirements
6```bash
7# Check GTK4 installation
8pkg-config --modversion gtk4  # Should be >= 4.0
9
10# Check WebKitGTK 6.0
11pkg-config --modversion webkitgtk-6.0  # Should be >= 2.40
12
13# Check Vulkan support (optional but recommended)
14vulkaninfo | grep "Vulkan Instance Version"
15```
16
17### Install Dependencies (Arch Linux)
18```bash
19sudo pacman -S webkit2gtk-6.0 gtk4 vulkan-tools
20```
21
22### Install Dependencies (Ubuntu/Debian)
23```bash
24sudo apt install libwebkitgtk-6.0-dev libgtk-4-dev vulkan-tools
25```
26
27## Build and Test
28
29### 1. Switch to Feature Branch
30```bash
31git checkout 004-migrate-to-webkitgtk
32```
33
34### 2. Build the Browser
35```bash
36make clean
37make build
38```
39
40### 3. Verify GPU Rendering
41
42#### Test Auto-Detection (Default)
43```bash
44# Should auto-detect GPU availability
45./dumber browse https://webglsamples.org/aquarium/aquarium.html
46```
47
48#### Force GPU Mode
49```bash
50# Force GPU acceleration
51./dumber browse --rendering-mode=gpu https://webglsamples.org/aquarium/aquarium.html
52
53# Or using environment variable
54DUMBER_RENDERING_MODE=gpu ./dumber browse https://example.com
55```
56
57#### Force CPU Mode
58```bash
59# Force software rendering
60./dumber browse --rendering-mode=cpu https://example.com
61
62# Or shorthand
63./dumber browse --disable-gpu https://example.com
64```
65
66#### Debug GPU Compositing
67```bash
68# Show GPU layer borders
69./dumber browse --debug-gpu https://example.com
70```
71
72### 4. Check Rendering Status
73```bash
74# While browser is running, check status
75curl http://localhost:8080/api/rendering/status
76```
77
78Expected response:
79```json
80{
81  "mode": "auto",
82  "gpu_active": true,
83  "gpu_available": true,
84  "vulkan_enabled": true,
85  "errors": [],
86  "performance": {
87    "fps": 60,
88    "cpu_usage_percent": 15.2,
89    "gpu_usage_percent": 45.8,
90    "memory_mb": 256
91  }
92}
93```
94
95## Performance Testing
96
97### 1. Benchmark Page Load
98```bash
99# Measure with GPU
100time ./dumber browse --rendering-mode=gpu https://browserbench.org/MotionMark/
101
102# Measure with CPU
103time ./dumber browse --rendering-mode=cpu https://browserbench.org/MotionMark/
104```
105
106### 2. Monitor Resource Usage
107```bash
108# In another terminal, monitor GPU
109nvidia-smi -l 1  # For NVIDIA
110radeontop        # For AMD
111
112# Monitor CPU
113htop
114```
115
116### 3. Test WebGL Performance
117```bash
118# High-demand WebGL test
119./dumber browse https://webglsamples.org/dynamic-cubemap/dynamic-cubemap.html
120
121# Check FPS counter in browser
122```
123
124## Troubleshooting
125
126### GPU Not Detected
127```bash
128# Check Vulkan drivers
129vulkaninfo
130
131# Check OpenGL
132glxinfo | grep "OpenGL renderer"
133
134# Force CPU mode if GPU issues
135./dumber browse --disable-gpu
136```
137
138### Performance Issues
139```bash
140# Enable debug indicators
141./dumber browse --debug-gpu https://example.com
142
143# Check for compositing issues (red borders = repaints)
144```
145
146### Build Errors
147```bash
148# Ensure correct pkg-config
149pkg-config --libs webkitgtk-6.0 gtk4
150
151# Clean and rebuild
152make clean
153make build
154```
155
156## Validation Checklist
157
158- [ ] Browser builds successfully with WebKitGTK 6.0
159- [ ] Browser starts in < 500ms
160- [ ] GPU acceleration activates when available
161- [ ] CPU fallback works when GPU unavailable
162- [ ] WebGL content renders correctly
163- [ ] No visual artifacts or rendering issues
164- [ ] History and bookmarks preserved
165- [ ] All existing features work
166- [ ] Performance improved with GPU enabled
167- [ ] Resource usage within acceptable limits
168
169## Migration Verification
170
171### Check API Usage
172```bash
173# Verify new GTK4/WebKit6 symbols
174ldd ./dumber | grep -E "(gtk-4|webkit.*6)"
175
176# Should see:
177# libgtk-4.so.1
178# libwebkitgtk-6.0.so.4
179```
180
181### Test Key Features
1821. **Navigation**: URLs load correctly
1832. **History**: Previous data accessible
1843. **Zoom**: Ctrl+Plus/Minus works
1854. **DevTools**: F12 opens inspector
1865. **Dmenu**: Integration still works
187
188## Report Issues
189
190If you encounter issues:
1911. Note the rendering mode used
1922. Check `/tmp/dumber.log` for errors
1933. Run with `--debug-gpu` for visual debugging
1944. Report with output of `vulkaninfo` and `glxinfo`

Keyboard shortcuts

Single-key shortcuts are on. ctrl k and esc work whatever this says.

ctrl k :
go to a section, branch, tag, file or repository
?
this list
j k
move the row cursor down / up
enter
open the row under the cursor; on Files, a directory opens or closes in place
↑ ↓ ← → home end
in the file tree (focus on a row): previous / next row, close / open a directory or go to its parent / first entry, first / last row. They never open a file
l h
on Files: open a directory or a file / close a directory or go up to its parent, then to the parent page. Elsewhere: into the side panel (on a merge request, its files) / back to the content; there j k move between its controls
g g G
first / last row
/
filter the list; on Files, find a file anywhere in the repository (esc clears, enter opens the best match)
b
switch branch or tag
g s g f g c g b g m g i g r g a
tabs: summary, files, commits, branches & tags, merge requests, issues, releases, actions (when available)
g h
home
w
wide mode: use the whole width of the screen, or not (remembered)
y
copy a permalink pinned to the commit
d u x
diff: split / unified / collapse or expand all
e E
diff: the whole file in view / every file, with the lines the hunks hide
n
merge request: next note in the diff
esc
close a dialog, leave a field

Branches 8

Tags 42

↑↓ moveenter openesc close