V0.6 native library loading support

Author: SuperIlu

.gitignore

@@ -15,3 +15,7 @@ duktape-2.5.0/djgpp/
 *.d
 dzcomm/obj/djgpp/asmdef.s
 doc/
+dexport.c
+*.dxe
+jSH-cppcheck-build-dir/
+*.undef

CHANGELOG.md

@@ -1,3 +1,8 @@
+**V0.6 native library loading support**
+* added support to load DXEs during runtime to extend functionality
+* moved comport to a loadable library
+* re-added KbHit()
+
 **V0.5 backport to musj**
 * switched back to MuJS for DOjS compatibility
 * added watt32 TCP/IP support

LICENSE

@@ -17,7 +17,7 @@ The documentation states:
 
 MIT License
 
-Copyright (c) 2019-2020 Andre Seidelt <[email protected]>
+Copyright (c) 2019-2021 Andre Seidelt <[email protected]>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

Makefile

@@ -1,30 +1,36 @@
 ###
-# Makefile for cross compiling DOjS for FreeDOS/MS-DOS
+# Makefile for cross compiling jSH for FreeDOS/MS-DOS
 # All compilation was done with DJGPP 7.2.0 built from https://github.com/andrewwutw/build-djgpp
 ###
 # enter the path to x-djgpp here
 #DJGPP=/Users/iluvatar/tmp/djgpp/bin
 DJGPP=/home/ilu/djgpp/bin
 
-MUJS=mujs-1.0.5
-DZCOMMDIR=dzcomm
-LIBDZCOMM=$(DZCOMMDIR)/lib/djgpp/libdzcom.a
-WATT32=watt32-2.2dev.rel.11/
-KUBAZIP=zip
+# subdirs
+MUJS		= mujs-1.0.5
+DZCOMMDIR	= dzcomm
+LIBDZCOMM	= $(DZCOMMDIR)/lib/djgpp/libdzcom.a
+WATT32		= watt32-2.2dev.rel.11/
+KUBAZIP		= zip
 
-INCLUDES=-I$(MUJS) -I$(DZCOMMDIR)/include -I$(WATT32)/inc -I$(KUBAZIP)/src
-LIBS=-lmujs -lm -lemu -ldzcom -lwatt
+# compiler
+CDEF		= -DGC_BEFORE_MALLOC #-DDEBUG_ENABLED #-DMEMDEBUG 
+CFLAGS		= -MMD -Wall -std=gnu99 -O2 -march=i386 -mtune=i586 -ffast-math $(INCLUDES) -fgnu89-inline -Wmissing-prototypes $(CDEF)
+INCLUDES	= -I$(realpath $(MUJS)) -I$(realpath $(DZCOMMDIR))/include -I$(realpath $(WATT32))/inc -I$(realpath $(KUBAZIP))/src -I$(realpath .)
 
-CDEF=-DGC_BEFORE_MALLOC #-DDEBUG_ENABLED #-DMEMDEBUG 
-CFLAGS=-MMD -Wall -std=gnu99 -O2 -march=i386 -mtune=i586 -ffast-math $(INCLUDES) -fgnu89-inline -Wmissing-prototypes $(CDEF)
-LDFLAGS=-L$(MUJS)/build/release -L$(DZCOMMDIR)/lib/djgpp -L$(WATT32)/lib
+# linker
+LIBS		= -lmujs -lm -lemu -ldzcom -lwatt
+LDFLAGS		= -L$(MUJS)/build/release -L$(DZCOMMDIR)/lib/djgpp -L$(WATT32)/lib
 
-EXE=JSH.EXE
-RELZIP=jsh.zip
+# output
+EXE				= JSH.EXE
+RELZIP			= jsh.zip
 
-BUILDDIR=build
-
-DOCDIR=doc/html
+# dirs/files
+BUILDDIR		= build
+DOCDIR			= doc/html
+DXE_TEMPLATE	= dxetemplate.txt
+DXE_EXPORTS		= dexport.c
 
 CROSS=$(DJGPP)/i586-pc-msdosdjgpp
 CROSS_PLATFORM=i586-pc-msdosdjgpp-
@@ -33,21 +39,25 @@ AR=$(DJGPP)/$(CROSS_PLATFORM)ar
 LD=$(DJGPP)/$(CROSS_PLATFORM)ld
 STRIP=$(DJGPP)/$(CROSS_PLATFORM)strip
 RANLIB=$(DJGPP)/$(CROSS_PLATFORM)ranlib
+DXE3GEN = dxe3gen
+DXE3RES = dxe3res
 export
 
 PARTS= \
 	$(BUILDDIR)/zip/src/zip.o \
 	$(BUILDDIR)/file.o \
-	$(BUILDDIR)/comport.o \
 	$(BUILDDIR)/funcs.o \
 	$(BUILDDIR)/jsconio.o \
 	$(BUILDDIR)/zipfile.o \
 	$(BUILDDIR)/watt.o \
 	$(BUILDDIR)/socket.o \
 	$(BUILDDIR)/lowlevel.o \
-	$(BUILDDIR)/jSH.o
+	$(BUILDDIR)/jSH.o \
+	$(BUILDDIR)/dexport.o
+
+DXE_DIRS := $(wildcard *.dxelib)
 
-all: init libmujs dzcomm libwatt32 $(EXE)
+all: init libmujs dzcomm libwatt32 $(EXE) $(DXE_DIRS)
 
 libmujs: $(MUJS)/build/release/libmujs.a
 
@@ -74,9 +84,15 @@ $(BUILDDIR)/%.o: %.c Makefile
 $(BUILDDIR)/zip/src/%.o: $(KUBAZIP)/src/%.c Makefile
 	$(CC) $(CFLAGS) -c $< -o $@
 
+$(DXE_DIRS):
+	$(MAKE) -C $@
+
+$(DXE_EXPORTS): dxetemplate.txt $(MUJS)/mujs.h
+	python3 ./extract_functions.py $(DXE_TEMPLATE) $(MUJS)/mujs.h $@
+
 zip: all doc
 	rm -f $(RELZIP)
-	zip -9 -v -r $(RELZIP) $(EXE) JC.JS JC.BAT CWSDPMI.EXE LICENSE README.md CHANGELOG.md jsboot/ scripts/ $(DOCDIR)
+	zip -9 -v -r $(RELZIP) $(EXE) JC.JS JC.BAT CWSDPMI.EXE LICENSE README.md CHANGELOG.md jsboot/ scripts/ $(DOCDIR) *.dxe
 
 doc:
 	rm -rf $(DOCDIR)
@@ -91,9 +107,12 @@ init:
 clean:
 	rm -rf $(BUILDDIR)/
 	rm -f $(PARTS) $(EXE) $(ZIP) JSLOG.TXT
+	for dir in $(DXE_DIRS); do \
+		$(MAKE) -C $$dir -f Makefile $@; \
+	done
 
-distclean: clean jsclean dzclean wattclean
-	rm -rf $(DOCDIR) TEST.TXT JSLOG.TXT
+distclean: clean jsclean dzclean wattclean dxeclean
+	rm -rf $(DOCDIR) TEST.TXT JSLOG.TXT *.dxe
 
 dzclean:
 	$(MAKE) -C $(DZCOMMDIR) clean
@@ -107,10 +126,13 @@ wattclean:
 zclean:
 	$(MAKE) -C $(ZLIB) -f Makefile.dojs clean
 
+dxeclean:
+	rm -f $(DXE_EXPORTS)
+
 fixnewlines:
 	find . -iname *.sh -exec dos2unix -v \{\} \;
 
-.PHONY: clean distclean init doc
+.PHONY: clean distclean init doc $(DXE_DIRS)
 
 DEPS := $(wildcard $(BUILDDIR)/*.d)
 ifneq ($(DEPS),)

Makefile.dxemk

@@ -0,0 +1,14 @@
+all: $(DXE_NAME) check_exports
+
+clean distclean:
+	rm -rf *.dxe *.d *.o *.undef
+
+%.o: %.c
+	$(CC) -o $@ -c $(CFLAGS) $<
+
+%.dxe: %.o
+	$(DXE3GEN) -o $@ $< $(DXE_LDFLAGS) -U -E _init_ -E _shutdown_ -V | tee $(basename $@).undef | sort
+	cp $@ ..
+
+check_exports: $(DXE_NAME) ../$(DXE_TEMPLATE)
+	python3 ../check_exports.py ../$(DXE_TEMPLATE) $(basename $<).undef

README.md

@@ -60,7 +60,7 @@ I used the following command lines to update/install my dependencies:
 ```bash
 sudo apt-get update
 sudo apt-get dist-upgrade
-sudo apt-get install bison flex curl gcc g++ make texinfo zlib1g-dev g++ unzip htop screen git bash-completion build-essential npm python-yaml zip dos2unix
+sudo apt-get install bison flex curl gcc g++ make texinfo zlib1g-dev g++ unzip htop screen git bash-completion build-essential npm python-yaml zip dos2unix python3
 sudo npm install -g jsdoc
 sudo npm install -g better-docs
 ```
@@ -73,6 +73,8 @@ export DJGPP_PREFIX=/home/ilu/djgpp
 ./build-djgpp.sh 7.2.0
 ```
 
+Make sure `dxe3gen` and `dxe3res` are installed as well and set `DJPATH` permanently to your installation directory of DJGPP.
+
 ## Getting & Compiling jSH
 Open a shell/command line in the directory where you want the source to reside.
 
@@ -86,6 +88,17 @@ Open the Makefile in a text editor and change the path to DJGPP according to you
 Now you are ready to compile jSH with `make clean all`. This might take some time as the dependencies are quite a large.
 `make distclean` will clean dependencies as well. `make zip` will create the distribution ZIP and `make doc` will re-create the HTML help.
 
+## Creating native libraries (DXEs)
+Have a look at the example libraries in `test.dxelib/` and `test2.dxelib/`. Some rules:
+* A library called `foo` must have the filename `foo.dxe` and must provide at least the function `void init_foo(js_State *J)`. This function is called when the library is loaded and can then register global variables/objects/classes/function in the Javascript runtime.
+* The library may also provide the function `void shutdown_foo(void)` (this is completely optional). This will get called during shutdown and can perform cleanup.
+* All libraries in the sourcetree will be build by the `make all` target if their dir-name ends with `.dxelib`. The Makefile in the directory must provide the targets all, clean and distclean (see examples).
+* Libraries should use the `Makefile.dxemk` whenever possible.
+* In theory it should be possible to compile additional native libraries without re-compiling `jSH.EXE` if the same compiler is used (see above). 
+* Native libraries may use all functions from `mujs.h` and all functions in `dxetemplate.txt`. If additional functions are needed these need to be included in the template and `jSH.EXE` must be recompiled!
+* When libraries are compiled the exports provided by jSH are checked against the used functions (see `check_exports.py`) and the build fails if there are symbols missing.
+* Feel free to provide your native libraries and/or changes to `dxetemplate.txt` for inclusion in the jSH GitHub repository (MIT license please)...
+
 # History
 See the [changelog](/CHANGELOG.md) for the projects history.
 

check_exports.py

@@ -0,0 +1,39 @@
+import sys
+import re
+
+if len(sys.argv) < 2:
+    print("Usage:\n  {} <template> <undef file>".format(sys.argv[0]))
+    exit(1)
+
+fd = re.compile(r"unresolved: `_(\w*)'")
+
+had_errors = False
+
+with open(sys.argv[1], "r") as template:
+    with open(sys.argv[2], "r") as undeffile:
+
+        # create a set with available exports
+        exports = []
+        for l in template:
+            l = l.strip()
+            if not l.startswith("//") and not l.startswith("#") and len(l) > 0:
+                exports.append(l)
+        available = set(exports)
+
+        # check if all symbols exist
+        for l in undeffile:
+            res = fd.search(l)
+            if res:
+                func = res.group(1)
+                if not func.startswith("js_"):
+                    if func not in exports:
+                        had_errors = True
+                        print("WARNING: DXE export '{}' missing!".format(func))
+
+# fail if there were missing symbols
+if had_errors:
+    print("\n\n!!! DXE export check FAILED!\n\n")
+    exit(1)
+else:
+    print("DXE export check OK!")
+    exit(0)

comport.dxelib/Makefile

@@ -0,0 +1,4 @@
+DXE_LDFLAGS	= -L../$(DZCOMMDIR)/lib/djgpp -ldzcom
+DXE_NAME	= comport.dxe
+
+include ../Makefile.dxemk

comport.c renamed to comport.dxelib/comport.c

@@ -1,7 +1,7 @@
 /*
 MIT License
 
-Copyright (c) 2019-2020 Andre Seidelt <[email protected]>
+Copyright (c) 2019-2021 Andre Seidelt <[email protected]>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

comport.h renamed to comport.dxelib/comport.h

@@ -1,7 +1,7 @@
 /*
 MIT License
 
-Copyright (c) 2019-2020 Andre Seidelt <[email protected]>
+Copyright (c) 2019-2021 Andre Seidelt <[email protected]>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

doc/classes.js

@@ -58,6 +58,8 @@ File.prototype.WriteBytes = function (data) { };
  */
 /**
  * Open a COM port.
+ * Note: COM port functions must be activated/loaded by calling LoadLibrary("comport")!
+ * 
  * @class
  * @param {COM} port one of COM.PORT.x
  * @param {COM} baud one of COM.BAUD.x

doc/internal.js

@@ -22,6 +22,13 @@ JSH_VERSION = 0.0;
  * @module general
  */
 
+/**
+ * Load and initialize a native library (DXE). Native libraries must reside in the directory jSH.EXE was started from!
+ * 
+ * @param {string} name the base name of the library (e.g. if the library is called "foo.dxe" on disk you need to call LoadLibrary("foo")).
+ */
+function LoadLibrary(name) { }
+
 /**
  * Write data to stdout.
  * @param {string} s the string to print.

doc/jsdoc.conf.json

@@ -21,7 +21,7 @@
 			"outputSourceFiles": false
 		},
 		"better-docs": {
-			"name": "jSH V0.5",
+			"name": "jSH V0.6",
 			"hideGenerator": true,
 			"navLinks": [
 				{