August 3, 2019 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, but uses a "config" file which is read
by the automatic makefile system. 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, MingGW and DJGPP platforms there are currently additional special makefiles,
and Makefile_nr is used.
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 was not designed to be fully compatible with X11 it used to be quite some work to port X11 applications to
nano-X. NX11 is a wrapper library for nano-X which provides X11 compatibility.
Users of Microwindows may want to port X11 applications to it.
These applications will be linked with NX11 instead of
X11 directly. Many applications now are not based on X11 directly but using a GUI toolkit.
A lightweight library is FLTK which can be based well on NX11.
If you link an application with libNX11 you also have to link it with libnano-X, i.e. -lNX11 and -lnano-X.
Before this release NX11 was called NXlib, and was a separate archive to download. It now is included in the src/nx11 subdirectory in the Microwindows sources.
To compile the NX11 library, pick a config file that matches your target system from microwindows/src/Configs,
and copy it to microwindows/src/config. Then, set the following options and type "make".
NANOX=Y (build nano-X library and server)
NX11=Y (builds NX11 library)
NANOWM=Y (include built-in window manager in nano-X server)
NUKLEARUI=N (use older-style window frames, better match for FLTK graphics)
For this you have to compile Microwindows first for your particular system. In the Configs directory there are
example config files for various platforms. Rename the config file in the src directory to e.g. config.default
and copy the config file which fits your system into the src directory. E.g. "cp Configs/config.linux-X11 config".
In the config file, check that the path for the freetype2 headers is properly defined in the INCFT2LIB variable.
The default is set to "/usr/include". In this case the Makefile.rules file will add "freetype2" to this path so
this results in the path "/usr/include/freetype2". You can also specify "/usr/include/freetype2" or some other path
instead. 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 NX11 and nano-X plus
the nano-X server in the "/usr/local" directory so FLTK can access them there.
You can remove these again with the "sudo make cleanusr" command.
The following instructions are in sequence for the various versions of FLTK. Please refer to the bottom of this
section to compile the latest version.
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=/path/to/microwindows/src/nx11/X11-local/X11 \ --x-libraries=/path/to/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& 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=/path/to/microwindows/src/nx11/X11-local/X11 \ --x-libraries=/path/to/microwindows/src/lib \ --disable-xcursor \ --disable-xrenderModify the paths specified to match your situation.
./replace-lX11.sh makeinclude ./replace-lX11.sh fltk-configc) Change the following lines at the very end of the config.h file in the fltk directory:
#define HAVE_DLFCN_H 0 #define HAVE_DLSYM 0d) 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.
NX11 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 NX11, 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". 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 NX11 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 NX11).
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 NX11 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 the application linked with
the nano-X.a library will have the client part that communicates via sockets with this server.
So you first have to run nano-X before starting your application. A typical script for that
looks like this: "bin/nano-X & bin/$progname".
A script has been prewritten for you: src/runapp, usage: "./runapp 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 a separate nano-X server. The client and server parts
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 included in the server only if you set the NANOWM variable 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, NX11 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 libNX11 instead of libX11 like this:
#X11_LIBS = $(shell pkg-config --libs x11 xext) X11_LIBS = -L../lib -lNX11 -lnano-XThen 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 & ./mupdf-x11 install.pdfThis assumes that you put Microwindows into your home directory too and compiled it there. If you did a "make install"
Georg Potthast
.