README.md

Docs | Changelog

Wiish (Why Is It So Hard) GUI framework might one day make it easy to develop, package and deploy auto-updating, cross-platform applications for desktop and mobile. If it succeeds, maybe the name will have to change :)

Wiish is currently ALPHA quality software. Don't make anything with it unless you're willing to rewrite it when this package changes.

Quickstart

1. Install Nim and nimble

2. Install Wiish:

   nimble install https://github.com/iffy/wiish.git

3. Find out what other dependencies you need:

   wiish doctor

4. Create a project and run it:

   wiish init somedir
   cd somedir
   wiish run

See wiish --help for more, but here are other examples. Some only work within a Wiish project:

wiish run --os ios-simulator
wiish run --os android
wiish build

Features

Wiish provides:

1. A wiish command line tool for running, building and packaging apps.
2. A wiish Nim library (i.e. import wiish/...) for app-specific helpers (e.g. auto-updating, asset-access, etc...)
3. Plugins for different GUI frameworks: import wiish/plugins/...

Plugins

Wiish uses a plugin system to support various GUI frameworks:

• wiish/plugins/webview - For webview apps based on oskca/webview.

The GUI component is designed to work separately from other features (e.g. auto-updating, packaging, etc...) so that different GUI libraries can be swapped in/out.

It is hoped that more plugins will be introduced for other GUI frameworks.

Support Matrix

The following shows the support matrix of automated tests. Actual support may be better or worse than described here.

• Yes - For wiish run, this means that the application starts and continues running for a few seconds. For wiish build it means the build succeeded.
• No - Means it failed
• - - Means it's not supported (and isn't planned to be supported)
• Planned - Means it doesn't currently work, but we're planning on getting it to work.
• Untested - Means that it might work when run on a real computer, but our automated tests aren't yet capable of testing it. For instance, we haven't yet figured out how to run GUI applications on Windows so those are mostly marked Untested.

Host OS	--os	Example	wiish run	wiish build
windows	android	webview	Planned	Planned
windows	mobiledev	webview	Untested	-
windows	windows	plainwebview	Untested	Planned
windows	windows	webview	Untested	Planned
linux	android	webview	Planned	Yes
linux	mobiledev	webview	Yes	-
linux	linux	plainwebview	Yes	Planned
linux	linux	webview	Yes	Planned
mac	android	webview	Yes	Yes
mac	ios	webview	Planned	Planned
mac	ios-simulator	webview	Yes	Yes
mac	mobiledev	webview	Yes	-
mac	mac	plainwebview	Yes	Yes
mac	mac	webview	Yes	Yes

GUI-independent features

Feature	macOS	Windows	Linux	iOS	Android
App icons	Yes			Yes	Yes
wiish run logs stdout	Yes	Yes	Yes	Yes	Yes
Log files
Static assets	Yes			Yes	Yes
Automatic updating				-	-
File associations
Menu bar access				-	-

Distribution formats

Package	Supported	Code signing
macOS .dmg
Windows Portable
Windows Installer
Linux .AppImage
iOS .ipa
Android .apk	Yes

Examples

See the examples directory for more examples of how to use this library. You can also initialize a project using these examples with wiish init. See wiish init --help for information.

Plugins

webview

Messaging

When using the wiish/plugins/webview plugin, you send/receive strings between JavaScript and your Nim like this:

In JavaScript do this:

window.wiish = window.wiish || {};
wiish.onReady = () => {
    wiish.onMessage(message => {
        // Handle message from Nim
    })
    wiish.sendMessage("Hello Nim! -Sincerely JavaScript");
}

In Nim do this:

import wiish/plugins/webview/desktop
var app = newWebviewDesktopApp()
app.life.addListener proc(ev: DesktopEvent) =
  case ev.kind
  of desktopAppStarted:
    var win = app.newWindow(
      url = some_html_url,
    )
    win.onReady.handle:
      win.sendMessage("Hello JavaScript! -Sincerely Nim")
    win.onMessage.handle(msg):
      discard "Handle message from JavaScript"
app.start()

A note on quality

This library works as advertised, but it is a huge mess. I'm learning as I'm going, and trying to wrangle all these platforms is ridiculous. I happily welcome suggestions (and pull requests).

Developing wiish

See CONTRIBUTING.md for information about contributing to Wiish development.