Verified Commit 3d4029ee authored by Camil Staps's avatar Camil Staps 🚀

Add README.md

parent 871ed297
# 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/
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment