New command line platforms that support event loops and workers (win, mac, lin)

contributed/cli/README.md

@@ -0,0 +1,45 @@
+# Command line (cli) controller
+
+Extends Moddable to be able to provide command line program using the `cli-<platform>` platform type, including
+`cli-win` for Windows, `cli-mac` for Mac, and `cli-lin` for Linux.  Includes support host/mod loading, timers,
+promises and workers.
+
+## Running your program
+
+When you build, such as `mcconfig -m -d -p cli-win`, the resulting program will be a native app (such as `.exe` on
+windows, or `.app` on mac).  If you run that program with no command line arguments, the default exported `main`
+function will be called.  The code will continue to operate, including support for Timer and other async services.  If
+you need to terminate the app under control of the program, use:
+
+```
+function abort(status) @ "fxAbort";
+
+fxAbort(status);    // status is the exit code the program will terminate with
+```
+
+## Using mods
+
+It you specify a path to a mod file (`.xsa` file, built with `mcrun`) as the first argument to the program, it will be
+loaded and symbols resolved before the `main` exported function is called.  This is slightly different than how the
+microcontrollers consume mods (from the flash `xs` partition, upon reboot) or how the simulators consume mods (provided
+via the `mcrun` program while a host waits for the module to be presented), but the resulting functionality remains 
+the same.
+
+## Using the debugger and instrumentation
+
+Full support for the debugger and instrumentation is included, and it should behave the same as using other platform
+types.  Instrumentation is updated once per second.
+
+## Linux requires X Windows System
+
+The Moddable implementation for Linux depends on the GTK3+ libraries, and as such even though a console application is
+built using `cli`, it still depends on X being installed.  This means that running the Linux console application from
+`telnet` or `ssh`, or from a server-based (non-desktop) Linux distro will not work.  You should be able to execute it 
+by installing X and also using the `xvfb` module (which implements a headless X frame buffer), but this has not been
+tested yet.  If you try this and find a recipe that works, please submit a pull and update this documentation
+accordingly.  
+
+A great future project for someone is to consider implementing a generic console machine across all of Moddable using
+the `libuv` event handler, which is the event handler from Node.  It is cross-platform and should allow for building
+command line programs on a wide range of platforms without the need for X or any window manager, assuming other
+cross-platform libraries are also consumed in the process for operations like files, resources, etc.

contributed/cli/cli-lin/main.c

@@ -0,0 +1,149 @@
+/*
+ * Copyright (c) 2020 Chris Midgley
+ *
+ *   This file is part of the Moddable SDK Tools.
+ * 
+ *   The Moddable SDK Tools is free software: you can redistribute it and/or modify
+ *   it under the terms of the GNU General Public License as published by
+ *   the Free Software Foundation, either version 3 of the License, or
+ *   (at your option) any later version.
+ * 
+ *   The Moddable SDK Tools is distributed in the hope that it will be useful,
+ *   but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *   GNU General Public License for more details.
+ * 
+ *   You should have received a copy of the GNU General Public License
+ *   along with the Moddable SDK Tools.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+/*
+    This file implements a cli-lin platform for Moddable that supports an event loop and dynamically loaded
+    archives (mods).  It implements the C main function, and starts up GTK with an invisible window to run
+	the actual program.  It manages clearn termination upon receipt of ^C, and performs instrumentaton updates
+	once/second.
+
+	This code is built upon GTK3 because the core of the Moddable "lin" platform is built upon GTK.  This means
+	that this "cli" application will not work on SSH or headless Linux without installing X and likely using
+	xvfb (x frame buffer).  
+
+*/
+
+#include "xsAll.h"
+#include <stddef.h>
+#include <stdlib.h>
+#include <stdio.h>
+#include "cli.h"
+#include <signal.h>
+#include <gtk/gtk.h>
+#include <sys/mman.h>
+#include <fcntl.h>
+
+static GtkApplication *gxApplication = NULL;
+static GtkWindow *gxWindow;
+static GtkApplication *app;
+
+#ifdef mxInstrument
+/*
+	Updates Moddable instrumentation once/second - called from GTK timer (see onApplicationActivate for where
+	the timer is started)
+*/
+gboolean  sendInstrumentation(gpointer userData) {
+    instrumentMachine();   
+	return TRUE;
+}
+#endif
+
+/*
+	Map an archive (mod) into memory.  Accepts the path to the archive, and returns either a pointer to the 
+	memory mapped image, or NULL if there was a failure during the loading of the file.
+*/
+void *loadArchive(char *archivePath) {
+	struct stat statbuf;
+	int archiveFile;
+
+	archiveFile = open(archivePath, O_RDWR);
+	if (archiveFile < 0) {
+		fprintf(stderr, "Filed to load archive %s (error %s)\n", archivePath, strerror(errno));
+		return NULL;
+	}
+	fstat(archiveFile, &statbuf);
+	void *archiveMapped = mmap(NULL, statbuf.st_size, PROT_READ|PROT_WRITE, MAP_SHARED, archiveFile, 0);
+	if (archiveMapped == MAP_FAILED) {
+		fprintf(stderr, "Filed to map archive %s (error %s)\n", archivePath, strerror(errno));
+		return NULL;
+	}
+	return archiveMapped;
+}
+
+/*
+	GTK handler for when the application is shutdown.  Cleanly terminates the XS machine.
+*/
+void onApplicationShutdown(GtkApplication *app, gpointer it) {
+    // done - end our XS machine
+    endMachine();
+}
+
+/*
+	GTK handler for application startup, which is the first event we process when the app starts up.  Creates a window (but does not show it)
+	in order to keep the GTK application running until we are ready for a shutdown.  Also sets up the instrumentation timer (once/second for
+	instrumentation updates in the debugger)
+*/
+void onApplicationStartup(GtkApplication *app) {
+	// create a window to keep our application running, but don't show it (so we logically remain a console app)
+	gxWindow = (GtkWindow*)gtk_application_window_new(app);
+
+	// set up a timer for instrumentation updates once/second
+#ifdef mxInstrument
+	g_timeout_add(1000, sendInstrumentation, NULL);
+#endif
+}
+
+/*
+	GTK handler for when the application is activated, which happens if there are no commmand line arguments. We simply start up the 
+	VM with no mods.
+*/
+void onApplicationActivate(GtkApplication *app, gpointer it) {
+    startMachine(NULL);
+
+}
+
+/*
+	GTK handler for when a command line is provided.  We start up the VM using the path to the mod from the command line
+*/
+void onApplicationOpen(GtkApplication *app, GFile **files, gint c, const gchar *hint, gpointer it) {
+    // start up our VM, optionally with path to archive (mod)
+    startMachine(g_file_get_path(files[0]));
+}
+
+
+/*
+    Handler for intercepting the ctrl-C shutdown of the process, and instructs the CFRunLoop to shutdown
+*/
+void ctrlHandler(int sig) {
+	fprintf(stderr, "\nShutting down\n");
+    g_application_quit(G_APPLICATION(app));
+}
+
+/*
+    main - accepts a single optional command line argument that is the path to a mod to load
+
+    Sets a ^C handler (for clearn shutdown) and starts up the GTK application
+*/
+int main(int argc, char** argv) {
+	int status;
+
+    // take control over ^C handling
+    signal(SIGINT, &ctrlHandler);
+
+	app = gxApplication = gtk_application_new("tech.moddable.cli", G_APPLICATION_HANDLES_OPEN);
+	g_signal_connect(app, "startup", G_CALLBACK(onApplicationStartup), NULL);
+  	g_signal_connect(app, "activate", G_CALLBACK(onApplicationActivate), NULL);
+	g_signal_connect(app, "shutdown", G_CALLBACK(onApplicationShutdown), NULL);
+  	g_signal_connect(app, "open", G_CALLBACK(onApplicationOpen), NULL);
+	status = g_application_run(G_APPLICATION(app), argc, argv);
+
+	g_object_unref(app);
+	return status;
+}

contributed/cli/cli-mac/main.c

@@ -0,0 +1,114 @@
+/*
+ * Copyright (c) 2020 Chris Midgley
+ *
+ *   This file is part of the Moddable SDK Tools.
+ * 
+ *   The Moddable SDK Tools is free software: you can redistribute it and/or modify
+ *   it under the terms of the GNU General Public License as published by
+ *   the Free Software Foundation, either version 3 of the License, or
+ *   (at your option) any later version.
+ * 
+ *   The Moddable SDK Tools is distributed in the hope that it will be useful,
+ *   but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *   GNU General Public License for more details.
+ * 
+ *   You should have received a copy of the GNU General Public License
+ *   along with the Moddable SDK Tools.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+/*
+    This file implements a cli-mac platform for Moddable that supports an event loop and dynamically loaded
+    archives (mods).  It implements the C main function, sets up XS machine and starts a Mac CFRunLoop message loop.
+    Upon a close message (which is intercepted and sent upon ^C) it cleanly shuts down the XS machine.  It also
+    maintains the instrumentation updates, using a timer, on a once/second interval.
+*/
+
+#include "xsAll.h"
+#include <stddef.h>
+#include <stdlib.h>
+#include <stdio.h>
+#include "cli.h"
+#include <signal.h>
+#include <sys/mman.h>
+#include <fcntl.h>
+
+#ifdef mxInstrument
+/*
+    Called from a once/second timer (see runMessageLoop) and is used to trigger instrumentation for debugging
+*/
+static void sendInstrumentation(CFRunLoopTimerRef cfTimer, void *info) {
+    instrumentMachine();   
+}
+#endif
+
+/*
+	Map an archive (mod) into memory.  Accepts the path to the archive, and returns either a pointer to the 
+	memory mapped image, or NULL if there was a failure during the loading of the file.
+*/
+void *loadArchive(char *archivePath) {
+	struct stat statbuf;
+	int archiveFile;
+
+	archiveFile = open(archivePath, O_RDWR);
+	if (archiveFile < 0) {
+		fprintf(stderr, "Filed to load archive %s (error %s)\n", archivePath, strerror(errno));
+		return NULL;
+	}
+	fstat(archiveFile, &statbuf);
+	void *archiveMapped = mmap(NULL, statbuf.st_size, PROT_READ|PROT_WRITE, MAP_SHARED, archiveFile, 0);
+	if (archiveMapped == MAP_FAILED) {
+		fprintf(stderr, "Filed to map archive %s (error %s)\n", archivePath, strerror(errno));
+		return NULL;
+	}
+	return archiveMapped;
+}
+
+/*
+    Message loop that manages the XS virtual machine.  The machine is started up, a timer is created to update
+    instrumentation every second, and then the Mac message loop is executed.
+*/
+int runMessageLoop(char *pathToMod) {
+    // start up our VM
+    int error = startMachine(pathToMod);
+
+    // set up a timer for the instrumentation
+#ifdef mxInstrument
+	CFRunLoopTimerRef timer = CFRunLoopTimerCreate(kCFAllocatorDefault, CFAbsoluteTimeGetCurrent() + 1, 1, 0, 0, sendInstrumentation, NULL);
+	CFRunLoopAddTimer(CFRunLoopGetCurrent(), timer, kCFRunLoopCommonModes);
+#endif
+
+    // process the message loop until terminated
+    CFRunLoopRun();
+
+    // done - end our XS machine
+    endMachine();
+
+    return error;
+}
+
+/*
+    Handler for intercepting the ctrl-C shutdown of the process, and instructs the CFRunLoop to shutdown
+*/
+void ctrlHandler(int sig) {
+	fprintf(stderr, "\nShutting down\n");
+    CFRunLoopStop(CFRunLoopGetCurrent());
+}
+
+
+/*
+    main - accepts a single optional command line argument that is the path to a mod to load
+
+    Sets a ^C handler (for clearn shutdown) and starts up the VM and message pump
+*/
+int main(int argc, char* argv[]) {
+
+    // take control over ^C handling
+    signal(SIGINT, &ctrlHandler);
+
+    // start up the XS VM and run the message loop
+    int error = runMessageLoop((argc > 1) ? argv[1] : NULL);
+
+    return error;
+}