Add README.md

README.md

+# iTasks-Electron
+
+This project uses [iTasks][] as a backend for [Electron][] to create
+cross-platform native-like applications with Clean. It is hoped that it can,
+eventually, take on a place similar to the [ObjectIO][] library, which is not
+cross-platform.
+
+<sup>(For those unfamiliar with Electron: it allows you to build cross-platform
+desktop applications with JavaScript, HTML, and CSS, by including a Chrome
+engine in the application package.)</sup>
+
+This project is still in very early stages. Not enough projects have been built
+yet to get a clear picture of the combinators that would be useful to have.
+Building an application with iTasks-Electron currently almost certainly means
+contributing back to the library here, which you are very much invited to do.
+
+For example projects, see:
+
+- [TextSheets][]
+- [SoccerFun-web][] (please request permission if needed)
+
+## Overview
+
+The idea is as follows:
+
+- The main JavaScript application starts an iTasks server in the background.
+
+- The iTasks server runs an Electron task which communicates over a different
+  TCP channel from the normal `onRequest` tasks. It uses the
+  `ABC.Interpreter.JavaScript` interface to JavaScript to run JavaScript code
+  on the main JavaScript process to interface with Electron. In this way it can
+  for example open a [`BrowserWindow`][Electron-BrowserWindow].
+
+- This `BrowserWindow` can open a normal `onRequest` task. In this way you are
+  running a plain iTasks application, only in a custom application window
+  rather than in the browser.
+
+- Alternatively, the `BrowserWindow` can make use of Electron tasks and bypass
+  the iTasks frontend completely. It then uses a straightforward interface to
+  send messages to and from the server. The client again acts on those messages
+  using the `ABC.Interpreter.JavaScript` foreign function interface.
+
+- The two ways of using `BrowserWindow`s can be combined in the same
+  application. Thus it is possible to use a fully customized main view, but use
+  iTasks generic editors for option dialogs, for example.
+
+## Installation
+
+1. Install [Node.js][] for your platform. Make sure that `npm` is in your path.
+
+2. Create a project and add iTasks-Electron as a git submodule:
+
+	```bash
+	git init my-project
+	cd my-project
+	git submodule add https://gitlab.science.ru.nl/cstaps/iTasks-Electron
+	```
+
+3. Create a Clean project:
+
+	```bash
+	cpm project myproject.prj create $CLEAN_HOME/etc/iTasks.prt
+	```
+
+4. Add `{Project}*iTasks-Electron*src` to your project's paths.
+
+5. Optionally, create a `package.json` for `npm` using `npm init`:
+
+	```bash
+	npm init
+	npm install --save-dev electron
+	```
+
+	(If you skip this step, the application will create a basic `package.json`
+	and install `electron` on the first run.)
+
+6. On linux, fix permissions of the Chrome sandbox:
+
+	```bash
+	sudo chown root:root node_modules/electron/dist/chrome-sandbox
+	sudo chmod 4755 node_modules/electron/dist/chrome-sandbox
+	```
+
+7. Create an `index.js` with the following contents:
+
+	```js
+	const process=require ('process');
+	
+	/* directory structure looks different for deployed applications */
+	if (__dirname.substr (__dirname.length-14).match (/[\/\\]resources[\/\\]app/))
+		process.chdir (require ('path').join (__dirname,'..','..'));
+	else
+		process.chdir (__dirname);
+	
+	const {run}=require ('./myproject-www/js/clean-electron.js');
+	run ({app: 'myproject'});
+	```
+
+	Replace `myproject` with the name of your project.
+
+You are now ready to write and compile your project. Use `serveElectron` in
+your `Start` rule.
+
+To run the application you only need to run the executable. You do not need to
+run the JavaScript code yourself; this is done automatically by Clean.
+
+[Electron]: https://www.electronjs.org/
+[Electron-BrowserWindow]: https://www.electronjs.org/docs/api/browser-window
+[iTasks]: https://gitlab.science.ru.nl/clean-and-itasks/iTasks-SDK/
+[Node.js]: https://nodejs.org/en/
+[ObjectIO]: https://clean.cs.ru.nl/Object_I/O
+[SoccerFun-web]: https://gitlab.science.ru.nl/cstaps/soccerfun-web
+[TextSheets]: https://gitlab.com/camilstaps/text-sheets/