Skip to content

Webversion introduction and integration #902

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
PavelSharp wants to merge 5 commits into
base: master
Choose a base branch
from
Open

Webversion introduction and integration #902

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
0fe3918
webver: Add webversion files.
PavelSharp Feb 16, 2026
c6fc0d2
webver: Add webver target in Makefile, fix echo output bug, refactoring
PavelSharp Feb 16, 2026
6e147a5
webver: Configure docs.yml to auto-deploy webversion
PavelSharp Feb 16, 2026
788bd1c
webver: Mention webversion in src/HEADER.md and in Readme.md
PavelSharp Feb 16, 2026
ba79b04
webver: improve documentation and naming consistency
PavelSharp Feb 22, 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
2 changes: 1 addition & 1 deletion .github/workflows/ccpp.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
name: C/C++ CI
name: Checkers
Copy link
Copy Markdown
Contributor

@RobLoach RobLoach Feb 22, 2026

Choose a reason for hiding this comment

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

Unrelated to this change?


on: [push, pull_request]

Expand Down
34 changes: 24 additions & 10 deletions .github/workflows/docs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,36 @@
name: Documentation on github.io
name: Docs, Webverion and Deploy

on:
push:
branches: [ master ]
on: [push, pull_request]
Copy link
Copy Markdown
Contributor

@RobLoach RobLoach Feb 22, 2026

Choose a reason for hiding this comment

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

Docs should only be built on pushes to master. Plan on fixing this up once it's merged?

Copy link
Copy Markdown
Contributor Author

@PavelSharp PavelSharp Feb 22, 2026

Choose a reason for hiding this comment

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

Just to clarify, this is already covered in the Mini FAQ. So my main question is should we build the webversion on pull requests?

Now, this PR prefers a "zero surprise" policy, which means we want to catch issues early before merging. This workflow also runs in parallel with ccpp.yml.
If that doesn't sound convincing, we could consider one of four options:

  • On pull_request: only build webver
  • On pull_request: only build docs [strange, but possible]
  • On pull_request: build both webver + docs [current behavior]
  • On pull_request: don't run docs.yml at all

Which would be better?

Copy link
Copy Markdown
Contributor

@sleeptightAnsiC sleeptightAnsiC Feb 22, 2026

Choose a reason for hiding this comment

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

Which would be better?

just like it was was before, only when pushing to master

Getting webver rebuild on each PR is costly and verbose. If it ever breaks, it will most likely be an issue with demo/sdl3_renderer (or with Emscripten, or with SDL itself) so full rebuild is unnecessary.

Instead, how about we use something similar to .github/ci_compile_sources.sh that will attempt to compile the demo with emcc without linking? (we will need SDL headers for this, so we have to deal with #897 first)

Copy link
Copy Markdown
Contributor

@RobLoach RobLoach Mar 8, 2026

Choose a reason for hiding this comment

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

Suggested change
on: [push, pull_request]
on:
push:
branches: [ master ]


jobs:
build-documentation:
build:
runs-on: ubuntu-latest
steps:
- name: checkout
uses: actions/checkout@v4
- name: apt-update
run: sudo apt-get update -qq
- name: apt-get doxygen
run: sudo apt-get install -y doxygen
#Documentation
- name: Install packages for docs
run: |
sudo apt-get update -qq
sudo apt-get install -y doxygen
Comment on lines +11 to +15
Copy link
Copy Markdown
Contributor

@RobLoach RobLoach Mar 7, 2026

Choose a reason for hiding this comment

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

Unrelated change

- name: build doc
run: make docs
- name: deploy
#Webversion
- name: Install packages for webver
run: |
sudo apt-get update -qq
Copy link
Copy Markdown
Contributor

@RobLoach RobLoach Mar 7, 2026

Choose a reason for hiding this comment

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

We already do an update prior to this. Don't need to do it again.

sudo apt-get install -y make
Copy link
Copy Markdown
Contributor

@RobLoach RobLoach Mar 7, 2026

Choose a reason for hiding this comment

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

Could bundle the make install with doxygen above

- name: Setup Emscripten SDK
uses: mymindstorm/setup-emsdk@v14
- name: Verify Emscripten
run: emcc -v
- name: Build SDL3 port for Emscripten
run: embuilder build sdl3
- name: Build webversion
run: make webver
#Deploy to GitHub Pages
- name: Deploy to GitHub Pages
if: ${{ github.event_name == 'push' && (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/feat/webver') }}
uses: peaceiris/actions-gh-pages@v4
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
Expand Down
40 changes: 29 additions & 11 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,18 @@

## path stuff
DOCS_PATH:=./doc
# Convenience shortcut to docs output path (as defined in Doxyfile)
DOCS_OUT:=$(DOCS_PATH)/html

DEMO_PATH=demo
SRC_PATH=src

WEBVER_BACKEND:=./demo/sdl3_renderer
WEBVER_SITE:=./webver/site
WEBVER_OUT:=$(DOCS_OUT)/webver
WEBVER_CFLAGS:=-O2 -DINCLUDE_ALL -sEXPORTED_RUNTIME_METHODS=requestFullscreen
Copy link
Copy Markdown
Contributor

@sleeptightAnsiC sleeptightAnsiC Feb 23, 2026

Choose a reason for hiding this comment

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

-O2 is fine, but you may consider -Os
People usually use -0s for release builds in Emscripten.
https://emscripten.org/docs/tools_reference/emcc.html#emcc-os

#Possible choice: ccall,cwrap,requestFullscreen,FS
WEBVER_CFLAGS+=${CFLAGS}
Comment on lines +14 to +19
Copy link
Copy Markdown
Contributor

@sleeptightAnsiC sleeptightAnsiC Feb 23, 2026

Choose a reason for hiding this comment

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

I feel like this section doesn't belong here.
Top level ./Makefile is meant for launching other makefiles/programs.
Can't we have configuration in something like vebver/Makefile instead?


## Documents settings
DOXYFILE:=$(DOCS_PATH)/Doxyfile
Expand Down Expand Up @@ -37,15 +46,16 @@ DEMO_LIST = $(shell find $(DEMO_PATH) -type f -name Makefile -printf "%h ")
######################################################################################


.PHONY: usage all demos $(DEMO_LIST)
.PHONY: usage all demos webver $(DEMO_LIST)
Copy link
Copy Markdown
Contributor

@RobLoach RobLoach Feb 23, 2026

Choose a reason for hiding this comment

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

Don't see a need to build the webver on every make run.

Copy link
Copy Markdown
Contributor

@RobLoach RobLoach Mar 8, 2026

Choose a reason for hiding this comment

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

Suggested change
.PHONY: usage all demos webver $(DEMO_LIST)
.PHONY: usage all demos $(DEMO_LIST)


usage:
echo "make docs to create documentation"
echo "make nuke to rebuild the single header nuklear.h from source"
echo "make demos to build all of the demos"
echo "make all to re-pack the header and create documentation"
@echo "make docs to create documentation"
@echo "make webver to build webversion on SDL3 + Emscripten (try to run 'embuilder build sdl3' if first time)"
@echo "make nuke to rebuild the single header nuklear.h from source"
@echo "make demos to build all of the demos"
@echo "make all to re-pack the header and create documentation"
Comment on lines +52 to +56
Copy link
Copy Markdown
Contributor

@RobLoach RobLoach Feb 23, 2026

Choose a reason for hiding this comment

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

@echo unrelated change.


all: docs nuke demos
all: docs webver nuke demos
demos: $(DEMO_LIST)


Expand All @@ -57,14 +67,12 @@ nuke: $(addprefix $(SRC_PATH)/, $(SRC))





########################################################################################
## Docs

docs: $(DOCS_PATH)/html/index.html
docs: $(DOCS_OUT)/index.html

$(DOCS_PATH)/html/index.html: $(DOCS_PATH)/doxygen-awesome-css/doxygen-awesome.css $(DOXYFILE)
$(DOCS_OUT)/index.html: $(DOCS_PATH)/doxygen-awesome-css/doxygen-awesome.css $(DOXYFILE)
doxygen $(DOXYFILE)

$(DOXYFILE):
Expand All @@ -75,6 +83,16 @@ $(DOCS_PATH)/doxygen-awesome-css/doxygen-awesome.css:



########################################################################################
## webver
Comment thread
RobLoach marked this conversation as resolved.

webver:
mkdir -p $(WEBVER_OUT)
Copy link
Copy Markdown
Contributor

@sleeptightAnsiC sleeptightAnsiC Feb 23, 2026

Choose a reason for hiding this comment

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

unless you have a very good reason to keep this line, you can probably remove it, and patch this instead

diff --git a/demo/sdl3_renderer/Makefile b/demo/sdl3_renderer/Makefile
index 48ee50e..22b83cd 100644
--- a/demo/sdl3_renderer/Makefile
+++ b/demo/sdl3_renderer/Makefile
@@ -47,7 +47,7 @@ DEP := ${TEMPDIR}/$(notdir ${BIN}).d
 SRC := main.c
 
 ${BIN}:
-    mkdir -p $(dir $@)
+    mkdir -p $(dir $@) ${TEMPDIR}
     ${CC} ${SRC} -o $@ -MD -MF ${DEP} ${cppflags} ${ldflags} ${ldlibs} ${cflags}
 
 ${BIN}: ${SRC}

emmake make -C $(WEBVER_BACKEND) CFLAGS="$(WEBVER_CFLAGS)" BIN=$(abspath $(WEBVER_OUT)/demo_sdl3_renderer.js) TEMPDIR=$(abspath $(WEBVER_OUT))
Comment on lines +89 to +91
Copy link
Copy Markdown
Contributor

@RobLoach RobLoach Feb 22, 2026

Choose a reason for hiding this comment

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

Since this it building out assets, we could take advantage of Makefile's command caching...

Suggested change
webver:
mkdir -p $(WEBVER_OUT)
emmake make -C $(WEBVER_BACKEND) CFLAGS="$(WEBVER_CFLAGS)" BIN=$(abspath $(WEBVER_OUT)/demo_sdl3_renderer.js) TEMPDIR=$(abspath $(WEBVER_OUT))
webver:
mkdir -p $(WEBVER_OUT)
$(WEBVER_OUT)/demo_sdl3_renderer.js: webver
emmake make -C $(WEBVER_BACKEND) CFLAGS="$(WEBVER_CFLAGS)" BIN=$(abspath $(WEBVER_OUT)/demo_sdl3_renderer.js) TEMPDIR=$(abspath $(WEBVER_OUT))

Copy link
Copy Markdown
Contributor

@sleeptightAnsiC sleeptightAnsiC Feb 23, 2026 •
edited
Loading

Choose a reason for hiding this comment

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

we could take advantage of Makefile's command caching...

@RobLoach This demo produces more files than just $(WEBVER_OUT)/demo_sdl3_renderer.js, so only catching this one here wouldn't be correct. Besides that, the demo/sdl3_renderer/Makefile is already caching under the hood (aka incremental build).

Also, the change that you suggested would not work, because this...

webver:
	mkdir -p $(WEBVER_OUT)

...would only end up calling mkdir and nothing else. What you probably had in mind was...

webver: $(WEBVER_OUT)/demo_sdl3_renderer.js

$(WEBVER_OUT)/demo_sdl3_renderer.js:
	mkdir -p $(WEBVER_OUT)
	emmake ...

...but as I said, this is unnecessary. This code is already okey as it is.

cp -r $(WEBVER_SITE)/* $(WEBVER_OUT)/
#[NOTE]We pass TEMPDIR directly for hide a potential issue
Copy link
Copy Markdown
Contributor

@RobLoach RobLoach Feb 22, 2026 •
edited
Loading

Choose a reason for hiding this comment

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

What potential issue are we hiding? It's probably best to not hide it. Building out to the temp directory instead of the destination directoy seems hacky.

Copy link
Copy Markdown
Contributor

@sleeptightAnsiC sleeptightAnsiC Feb 23, 2026

Choose a reason for hiding this comment

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

It needs tempdir because demo/sdl3_renderer/Makefile produces depfiles for incremental building, however, this whole TEMPDIR=$(abspath $(WEBVER_OUT)) hack dumps all those depfiles into WEBVER_OUT, so this whole thing seems wrong.

@PavelSharp What you did with BIN=$(abspath $(WEBVER_OUT)/demo_sdl3_renderer.js) should be already enough, it should already work with default tempdir and produce binaries under WEBVER_OUT as expected. If you're getting any "potential issue", just tell us what it is exactly.



########################################################################################
## Demos

Expand All @@ -87,4 +105,4 @@ $(DEMO_LIST):
## Utility helpers

clean:
rm -rf $(DOCS_PATH)/html $(OUTPUT)
rm -rf $(DOCS_OUT) $(OUTPUT)
2 changes: 2 additions & 0 deletions Readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@ draw commands describing primitive shapes as output. So instead of providing a
layered library that tries to abstract over a number of platform and
render backends, it focuses only on the actual UI.

<a href="https://immediate-mode-ui.github.io/Nuklear/webver" target="_blank">Try Nuklear in Browser</a>

## Features

- Immediate-mode graphical user interface toolkit
Expand Down
4 changes: 4 additions & 0 deletions src/HEADER.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,10 @@ commands describing primitive shapes as output. So instead of providing a
layered library that tries to abstract over a number of platform and
render backends it only focuses on the actual UI.

<a href="webver/index.html" target="_blank">Try Nuklear in Browser</a>

Nuklear in a <a href="webver/minshell.html" target="_blank">minimal shell</a> is also provided for compatibility and testing

## Highlights
- Graphical user interface toolkit
- Single header library
Expand Down
22 changes: 22 additions & 0 deletions webver/Readme.md
View file
Open in desktop
Copy link
Copy Markdown
Contributor

@RobLoach RobLoach Feb 23, 2026

Choose a reason for hiding this comment

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

Rename to README.md

Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
Webversion notes
===
Comment on lines +1 to +2
Copy link
Copy Markdown
Contributor

@RobLoach RobLoach Feb 22, 2026

Choose a reason for hiding this comment

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

Suggested change
Webversion notes
===
# Nuklear Web Demonstration


## Terminology

**Webversion** (or **webver** for short) is a demonstration of Nuklear being run in the browser via Emscripten.
Currently it supports only the SDL3 backend, but long-term, additional backends may be added.

We use the consistent term **webversion** because it is already referenced across other files and may appear in user-created issues and pull requests.

## Folder Structure

We use the `site` subfolder to store all public webversion files.
Current folder contains **internal** files for webversion support that do not need to be published.

## Update Policy

The webversion is auto-updated through CI/CD workflow scripts. Any push triggers an automated build and deployment process, so no manual steps are required.

## About Logo

The Nuklear logo was suggested by Rafał Jopek and published in [issue #401](https://github.com/Immediate-Mode-UI/Nuklear/issues/401#issuecomment-2066737874)
Comment on lines +20 to +22
Copy link
Copy Markdown
Contributor

@RobLoach RobLoach Feb 23, 2026

Choose a reason for hiding this comment

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

The logo is likely more broadly scoped to the Docs. If we are uploading it, may be good to have it displayed in the main docs, and credited there.

Binary file added webver/site/emscripten_logo.png
View file
Open in desktop
Copy link
Copy Markdown
Contributor

@RobLoach RobLoach Feb 22, 2026

Choose a reason for hiding this comment

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

There isn't a real reason to provide the Emscripten logo. Have the minshell be the default one?

Copy link
Copy Markdown
Contributor

@sleeptightAnsiC sleeptightAnsiC Feb 23, 2026 •
edited
Loading

Choose a reason for hiding this comment

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

These logos are used as hyperlinks, so it would be nice to keep this functionality in one way or another. Also, the images just look nice overall, and make some sense in showcase shell.

The only problem I have here is .PNG format. Git doesn't play well with binary files, and small .PNG can't scale with higher resolution. Vendoring this inside of git repo feels wrong.

Can't we use .SVG format instead? Aren't web browsers supporting this by default?
We already have .SVG version of nuklear logo, here: https://github.com/Immediate-Mode-UI/Nuklear/files/15042034/nuklear.zip
For the Emscripten logo we can embed it by referencing this link: https://raw.githubusercontent.com/sthagen/emscripten-core-emscripten/refs/heads/main/media/powered_by_logo.svg

Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added webver/site/favicon.ico
View file
Open in desktop
Binary file not shown.
Loading