2018/11/12 Microwindows FAQ2
Download the current version of Microwindows from GitHub.
Read the instructions in microwindows/src/README.
bin: compiled executables Configs: "config" file examples for different platforms, see Configs/README contrib: user contributed, TinyWidgets and alternative Makefile_nr make system for EMSCRIPTEN, Android and DJGPP demoscripts: outdated example scripts to execute demos. Use ./runapp instead, see src/README. docs: programming notes drivers: source code of the screen, mouse and screen device drivers ecos: special files for the ECOS operating system engine: source code for Microwindows graphics drawing and clipping engine fonts: fonts required for demo programs include: header files lib: compiled libraries mwin: source code for the Win32 API implementation nanox: source code for the Nano-X API implementation nx11: source code for the NX11 X11 compatibility library obj: temporary object files rtems: special files for the RTEMS operating system
Microwindows does not have a configure file. For all systems other than EMSCRIPTEN,
Android, or DJGPP, it uses a makefile based build system.
This are several linked Makefiles files which are called recursively. To customise
this for the various platforms there is a config file which you can edit. Examples of this
config file for different platforms are in the "src/Configs" directory.
For Android, EMSCRIPTEN, DJGPP and RTEMS platforms there are currently additional special makefiles.
Makefile_nr is used for MinGW, DJGPP and EMSCRIPTEN, and Makefile.rtems for RTEMS.
The Makefile, which is used for Linux and OSX includes Path.rules and the config file
mentioned above. Then it includes the Makefile.rules file which contains the clean and install
targets for Make and calls the Makefiles in the subdirectories. It also includes Arch.rules which
contains handling settings for the different platforms supported. The Makefiles in the subdirectories
will also include the Path.rules file, the config file plus Objects.rules files. They call the
Makefile.rules file again to compile the required files.
Since nano-X is not fully compatible to X11 it is quite some work to port X11 applications to
nano-X. NXlib is a wrapper library for nano-X which does provide X11 compatibility.
Users of Microwindows currently mainly want to port X11 applications to it. Writing applications
based on nano-X from scratch is rarely done. So applications are now based on NX11 instead of
nano-X directly. Furthermore applications now are not based on X11 directly but using a GUI toolkit.
For NX11 this is FLTK which can be based well on NX11.
If you link an application with libNXlib you also have to link it with libnano-X, i.e. -lNXlib and -lnano-X.
PXlib is a library that is NXlib plus nano-X compiled together. So when porting applications to
Microwindows you do not have to replace -lX11 with both -lNX11 and -lnano-X any more, just -lPXlib
will do.
Before this release NXlib was a separate archive to download. It now is added in the src/nx11 subdirectory to the
Microwindows package.
For this you should compile Microwindows with the config.fltk file in the configs directory. Rename config
in the src directory to e.g. config.default and then copy the config.fltk file as config into the src directory.
When using the X11 platform, leave SHAREDLIBS=Y and LINK_APP_INTO_SERVER=N.
Then compile Microwindows and enter "sudo make install" to install the shared libraries PX11, NX11 and nano-X plus
the nano-X and nanowm programs in the "/usr" directory so FLTK can access them there.
You can remove these again with the "sudo make cleanusr" command.
Download FLTK 1.3.2 and cd into the fltk directory. If you are using a later version, you have to follow the
additional instructions provided below. Then enter:
./configure --x-includes=/home/georg/microwindows/src/nxlib/X11 \ --x-libraries=/home/georg/microwindows/src/lib \ --disable-gl \ --disable-xinerama \ --disable-xft \ --disable-xdbe \ --disable-xfixesModify the paths specified to match your situation. You can put this command into a script to repeat it if
./replace-lX11.sh makeinclude ./replace-lX11.sh fltk-configIf you are using Microwindows on the Linux X11 platform, you will need to make a patch to the FLTK source code
nano-X& nanowm& test/helloThis way the programs nano-X and nanowm will continue to run in the background and you can execute different demos
--enable-localjpeg \ --enable-localpng \ --enable-localzlib \ --disable-threads \
did_find_GTK_libs = 0; return;
--disable-xcursor \ --disable-xrender \
./configure --disable-gl \ --disable-xinerama \ --disable-xft \ --disable-xdbe \ --disable-xfixes \ --enable-localjpeg \ --enable-localpng \ --enable-localzlib \ --disable-threads \ --x-includes=/home/georg/microwindows/src/nxlib/X11 \ --x-libraries=/home/georg/microwindows/src/lib \ --disable-xcursor \ --disable-xrenderb) copy the file ./replace-lX11.sh into the fltk-1.4.x directory and run:
./replace-lX11.sh makeinclude ./replace-lX11.sh fltk-configc) add the line "#undef USE_XRANDR" right after the line "#define USE_XRANDR ..." in the files "src/Fl_x.cxx" (Line 53) and
#define HAVE_DLFCN_H 0 #define HAVE_DLSYM 0e) run "make" in the fltk directory now.
There is a separate application note in this directory for Android.
This means Microwindows has not found any truetype fonts on your platform und uses the default
system font.
Microwindows comes with a fonts directory which contains a number of fonts. You can copy that
into your application directory where your application then will usually find them.
Nano-X uses the path "fonts/truetype" as default.
NXlib will also scan the /usr/share/fonts directory for available fonts.
If your application requests fonts that are not available, you can set up a fonts.alias file
which will map the requested fonts to other fonts that are availabe. For DOS this file is
called fonts.ali. You can also use a fonts.alias file if you only want to provide just a few fonts
with your application to reduce the disk space required.
Finally you can specify the path to the truetype fonts on your system by setting the global
variable "TTFONTDIR" to this path. This variable is read by nano-X when searching for the truetype font.
Emscripten allows to compile a Microwindows application to Javascript and execute it
in a tab of Firefox or some other browser. The Microwindows implementation is based on
the SDL2 drivers.
First download and install the emscripten package using the instructions from this page:
Download and install
This are currently the following commands on the command line of a Linux terminal window which will download
about 400 MB of SDK tools.
git clone https://github.com/juj/emsdk.git cd emsdk git pull ./emsdk install latest ./emsdk activate latest source ./emsdk_env.shWithin your "emsdk" directory enter "source ./emsdk_env.sh" to set the required paths for
The MinGW port is based on the Allegro graphics library and the Makefile_nr file. You can
edit this file to use either Allegro4 or Allegro5. Depending on the Allegro library you specify
for linking it will be linked statically or as a shared library. If you link with a shared
library you have to distribute the corresponding Allegro dll with your application.
Do not select png or jpeg in the Makefile_nr file since these are only used for the nano-X demos
or other nano-X applications.
So download a binary version of Allegro for MinGW or compile Allegro with MinGW.
Run "make -f Makefile_nr" to compile Microwindows for MinGW.
There is an Allegro macro defined in the config file. If you set that the Allegro drivers
are compiled in and the Allegro library is linked with nano-X. Currently only Allegro5 does work
with Nano-X applications, NX11/FLTK does not work. Allegro4 does not yet work on Linux.
There are SDL macros defined in the config file. Use "src/Config/config.sdl"
Then the SDL2 driver is compiled in and is linked with nano-X.
To use Microwindows on DOS you need to compile with DJGPP. Once you have that set up use the
makedos.bat file to compile. This batch file calls "make -f Makefile_nr ARCH=DOS".
Since the configure script of the new application will not find NXlib or PXlib, it will look for
standard X11.
However, after you run ./configure on your Linux system you can edit the resulting Makefile and
replace in it the references to the "-lX11 and -lXext" libraries with "-lNX11 -lnano-X" or just
"-lPX11". Many applications will compile then.
You can also use the replace-lX11.sh script in the src directory to replace "-lX11 and -lXext" in a
Makefile or any other file for you. Enter the name of the makefile on the command line when executing
this script and it will replace "-lX11" and -lXext" with "-lNX11 and remove "-lXext" in this file.
You can also add "-e" as the second parameter. In this case "-lXext" will be replaced with "-lNXext".
"libNXext" is a library with stubs for the functions in the "libXext" library. You can use this if the
application you want to port uses functions from the libXext library.
The alternative is to modify the automake files so configure will generate a makefile that uses PXlib
instead of Xlib and Xext.
Follow e.g. the SDL example. Typically you will add a macro which selects the new drivers into the config file.
Then set the library your drivers may need to link with in Makefile.rules and the drivers to compile with
Microwindows in drivers/Objects.rules.
Also check the files "nanox/srvmain" und "mwin/winmain". These contain #if / #elseif statements for
different platforms which you will have to set for your platform too.
This are applications which are too large to be ported to Microwindows.
There is NanoGTK which is GTK version 1.2 ported to nano-X. With NXlib it is also possible to compile GTK1.
However, today there are almost no applications using GTK1 since that is not compatible with GTK2.
Greg Haerr did some tests with an early version of QT (qt-x11-2.3.1). The NX11 library was sufficiently
binary compatible to run demos compiled with QT.
In the early days of the Microwindows project there was a need for a GUI with widgets and dialogs.
It was decided to implement that as an Windows API compatible library called libmwin. So if you prefer
to code on the Windows API level you can use that. This library provides a Windows compatible API that
can be used on any platfrom that Microwindows will run on.
The Microwindows library therefore has two APIs: one is Windows API compatible (mwin) and one is
X11 compatible (nano-X with NXlib).
With the current support for FLTK it is usually better to start an application based on that. FLTK is a
more extensive GUI toolkit than the Windows API compatible mwin library.
Resource files describe the screen layout of a GUI when you are using Windows. The MWin API also supports
resource files. The screen layout is developed using a screen designer and stored in a resource file. This file
has the same name as the application program file but the ending is ".rc". Simple ".rc" files can also be written
by hand. The ".rc" file is then compiled with a resource compiler to a ".res" file.
If you use Dialog windows in your program, Microwindows will open a ".res" file with the same name as the program
to load the screen layout to use. Microwindows uses a separate file while Windows adds this file to the program file itself.
The demo programs, mwdialog and mwdvetest, put a logical link to their ".res" resource file into the "bin" directory.
To write the a resource file and compile it you can use the ResourceHacker program on Windows. This program can
also extract a ".rc" file from a ".res" file. On Linux there is a resource compiler called "windres".
Greg Haerr got Kaffe to work with Microwindows. This way you can run Java with Microwindows.
ELKS is 16bit version of Linux. The website is: http://elks.sourceforge.net/
Due to memory constraints ELKS does support version 0.86 of Microwindows only. This has been reenabled in the year 2017 and added
to the ELKS package. Details about this port are availabe at: https://github.com/jbruchon/elks/blob/master/nano-X/Readme-ELKS
If you set DEBUG = Y in the config file, printf statements you add into the code will work. Otherwise
Microwindows uses a #define macro to disable printf statements in the code.
Microwindows uses the DPRINTF/EPRINTF macros in debug mode to print information to the console
window. These are defined in the src/include/device.h header file.
If the HAVE_FPRINTF macro, also defined in this header file, is set to 0 in e.g. Arch.rules, fprintf/printf
will no longer work.
Nano-X and NXlib do support the mouse wheel, but not all mouse drivers in the drivers directory are adapted
to report more than three mouse buttons yet. Currently only the gpm, x11 and Allegro mouse driver report the
up- and down wheel movement.
The majority of the code was written over ten years ago and gcc constantly increased the number of warnings
from release to release. In debug mode the code is compiled with the -Wall parameter plus requesting some
additional warnings. This causes all these warnings with the old code base and it would take a very long
time to remove all these now.
In release mode the -Wall parameter is not set and Microwindows compiles with just a few warnings.
The Microwindows makefile is written as a recursive makefile and the main target cannot be run with this option.
However, the subdirectories can be compiled with this option and this is done automatically using the number of
processors in Make's $(nproc) variable if you set the PARALLEL option in the config file to "Y". This is the default now.
You can set MICROWIN = N and MICROWINDEMO = N in the config file to reduce compile time if you will
not use the MWin API and just use the X11 compatible API only. If you do not need the demo applications
you can set NANOXDEMO = N too to avoid these demos to be compiled.
Microwindows can be compiled to a separate server and window manager and the application linked with
the nano-X.a or mwin.a library will have the client part that communicates via sockets with this server.
So you first have to load nano-X and nanowm before starting your application. A typical script for that
looks like this: "bin/nano-X & bin/nanowm & bin/$progname".
If you set the LINK_APP_INTO_SERVER macro to "Y" Microwindows will compile to a single nano-X.a library and not
generate separate nano-X server und nanowm window manager programs. The client and server parts plus the window
manager are linked together to one library. If you link your application with this library, you do not have to
load the server before the application, you can just click on the application in your file manager and that will
start it. You can also start your application from the command line as a single program.
The window manager will be build only if you set the NANOWM macro to "Y". Otherwise the application will run
without this window manager and thus without window decorations.
If you set the SHAREDLIBS macro to "Y" the nano-X, NXlib etc. libraries are compiled as shared libries in
addition to being compiled to static libaries. So the application does not have to link statically with nano-X
or NX11 but can load these dynamically at runtime. You find all these libraries in the "src/lib" directory.
There is the "cleanusr" target in the makefile for that. So "sudo make cleanusr" will remove the files from /usr/bin,
/usr/lib and if availabe /usr/lib64.
You can enable e.g. the soft keyboard as a second keyboard. For this set the "2NDKBD" parameter in the "config" file to "Y".
This will cause the Makefile.rules file to set the macro "MW_FEATURE_TWO_KEYBOARDS" to one and the "pipe_kbd.c" driver will
be compiled. This driver uses a named pipe. You also have to set the LINK_APP_INTO_SERVER macro to "N". The soft keyboard example
in the "demos/nxkbd" directory will use the "pipe_kbd" driver. The nxkbd example is always compiled by the Makefile as part of
the demos.
To test the soft keyboard as the second keyboard you can execute the "nxkbd.sh" file in the "src/demoscripts" directory. This will
load both the soft keyboard and the "grabdemo" program. You can then click the keys on the soft keyboard which will be displayed in
the grabdemo program or type keys on your standard keyboard, the keys from both keyboards will be displayed.
In general the macro "MW_FEATURE_TWO_KEYBOARDS" has to be set to one and you have to set the parameter "KBDDEVICE kbddev2"
in the keyboard driver you want to use as the second keyboard. In the "pipe_kbd.c" program the "MW_FEATURE_TWO_KEYBOARDS" macro
selects whether the driver uses "kbddev" for the first and often only keyboard or or "kbdev2" for the second keyboard.
If you change the "KBDPIPE" macro in the "demos/nxkbd/srvconn.c" program to zero, it will not use the "pipe_kbd.c" driver but the
"GrInjectKeyboardEvent()" function of the Nano-X API to write the keyclick and keyrelease of the soft keyboard into the standard
event queue. Then you do not have to use the "MW_FEATURE_TWO_KEYBOARDS" macro.
The frame buffer emulator is an X11 program that emulates a frame buffer using Xlib. This allows to test frame buffer programs while
an X11 based desktop is loaded.
If you set FBEMULATOR=Y in the "src/config" file, the frame buffer emulator code in "src/demos/fbe.c" will be compiled. To get
Microwindows to use the frame buffer for screen output select FRAMEBUFFER=Y in the "src/config" file too. If you set FRAMEBUFFER=Y
Microwindows will compile and use the framebuffer screen driver in "drivers/scr_fb.c". In this code you have to set the desired
x/y resolution and color depth (bpp) which you plan to use. Set SCREEN_PIXTYPE=MWPF_TRUECOLORABGR in the "src/config" file for
32 bpp which we will use below. For initial testing select the NOMOUSE and NOKBD drivers.
To run the frame buffer emulator set the environment variable FRAMEBUFFER to: "FRAMEBUFFER=/tmp/fb0". The frame buffer driver
Microwindows is using reads this environment variable on startup.
Then execute the frame buffer emulator: "bin/fbe -d32&". The emulator will then run in the background. After that you can run your
Nano-X or Microwindows program which will use the frame buffer screen driver on the X11 desktop. To use a mouse and a keyboard you
also need to select drivers for these in the "src/config" file and unselect the NOMOUSE and NOKBD drivers in the config.fbe file.
The SERMOUSE and TTYKBD drivers should work. However, you have to allow read access to "dev/psaux" for the mouse and "dev/tty" for
the keyboard. Otherwise you get "error 13". So enter "sudo chmod 666 /dev/psaux" and ""sudo chmod 666 /dev/tty" before running your
application.
The frame buffer emulator supports the following command line options:
-x [X size], -y [Y Size], -t [Total X Size], -d [Color depths bpp(1,2,4,8,15,16,24,32)], -z [Zoom factor]
-r [Reverse bit order (1,2,4bpp LSB first)], -g [Gray palette (4bpp only)], -c [Force create new framebuffer (required when size changes)]
Download MuPDF from this link: https://mupdf.com/downloads/archive/mupdf-1.14.0-source.tar.gz
After unpacking the archive into your home directory change the Makerules file in line 131 to use libPX11 instead of libX11 like this:
#X11_LIBS = $(shell pkg-config --libs x11 xext) X11_LIBS = -L../lib -lPX11 -lNXextThen compile MuPDF with the following command:
make HAVE_GLUT=noThis will generate the executable file mupdf-x11 in the mupdf-1.14.0-source/build/release directory. To test we need a PDF document,
../../../microwindows/src/bin/nano-X -N & ../../../microwindows/src/bin/nanowm & ./mupdf-x11 install.pdfThis assumes that you put Microwindows into your home directory too and compiled it there. If you did a "make install"
12th of November 2018, Georg Potthast
.