Chapter 1. Getting Started With Microwindows

Table of Contents
Installing Microwindows
Hello World Example

Installing Microwindows

This document will guide you through installation of Microwindows onto a Linux host. At the end of this tutorial you will be able to execute the Microwindows demo applications in an X window that simulates the screen of your embedded device. You will also be able to create and execute a simple hello world application using the nano-X API.

In the following chapters you will also learn how to work with images and TrueType fonts.

Download The Latest Sources

Download the latest source code from the Microwindows ftp site. In the following example I'll be building revision 0.89pre7. The sources come in a tarball named microwindows-0.89pre7.tar.gz. Copy this file into a convenient spot. I copied the file into my home directory /home/gary.

Extract the sources. The tarball is a compressed tar file. You must first uncompress the file using gunzip, then extract the sources from the tar file using tar. This creates a new directory named microwin that contains the Microwindows source tree. Type the following commands.

$ tar -xzf microwindows-0.89pre7.tar.gz

Configure The Build Scripts

Change directories to the new Microwindows source directory.

$ cd microwin/src

You should take the time to read the file microwin/src/INSTALL and then look through the file microwin/src/config. There are many different options that you can compile into Microwindows. For now the only difference that you want from the default is to build for X11 display. When your application goes into your embedded system you will most likely want to use FRAMBUFFER drivers. But for now we will be prototyping our system on a desktop machine running X windows. This will let us see our output in a window on the same desktop as our compiler and debugger.

To build for X windows you need to first set the configuration file for the proper X11 settings. Luckily there are preset configurations in the microwin/src/Configs directory. Copy the file config.x11 over the file config.

$ cp Configs/config.x11 config

Build The Library And Demos

After making modifications to the configuration file you can build the Microwindows library and demo applications. Build the libraries and demos by typing:

$ make clean; make

You should add the microwindows binary directory to your path. We will be running applications in that directly quite a bit, especially when we start using nano-X. Run the following command, you may also want to add the command to your ~/.bashrc file.

$ export PATH=~/microwin/src/bin:$PATH

Run the WIN32 demos

Test the build by running a few of the Microwindows demo applications. Press the Pause key to exit each of these applications.

$ mine
$ mtest
$ mdemo
$ malpha

Currently the WIN32 layer of Microwindows can only support one application running on the desktop at a time. If you are interested in running multiple applications simultaneously you will need to use the nano-X layer of microwindows rather than the WIN32 layer.

Run the NANO-X demos

Also run a few of the nano-X demo applications. To run the nano-X applications you must first run the nano-X server, then the application. The following three commands will start a nano-X server, then start the nxclock application, then the nxscribble application. You will see a black screen with two windows, one for each application. Press the Break key to exit each of these applications.

$ nano-X & sleep 1
$ nxclock &
$ nxscribble & 

An alternative command line to accomplish the same thing is shown below. The sleep command is required to give the nano-X server a bit of time to initialize before starting the client applications.

$ nano-X& sleep 1; nxclock& nxscribble& 

You can't move the windows around within the nano-X screen, without the aid of a window manager. Luckily a window manager is included in the demo directory. Kill the previous demo by pressing the Break key. This time run the nanowm window manager before running the nxclock or nxscribble applications.

$ nano-X& sleep 1; nanowm& sleep 1; nxclock& nxscribble& 

Now you will see a cyan screen with two decorated windows, one for each application. The significant difference is not that we have a cyan background. The significant difference is that we have title bars on the two applications. Now you can move the windows around the screen by dragging their title bars. You can also exit an individual application. Try this by clicking the X button on the top of the nxclock window. The nxclock application will quit, while the nxscribble application continues to run. You can restart the nxclock application back at the command line, and a new clock window will appear.

Install The Libraries

If everything went as planned and the demo applications ran then you should install the libraries now. Switch to root user id and type:

# make install

This will copy the appropiate files to /usr/include/microwin and /usr/lib. You don't need to install the libraries to run the demo applications, but you will need them to build your own applications. The libraries that will be installed are:

 usr/lib/libmwdrivers.a 
 usr/lib/libmwengine.a 
 usr/lib/libmwfonts.a 
 usr/lib/libmwimages.a 
 usr/lib/libmwin.a 
 usr/lib/libmwinlib.a 
 usr/lib/libmwobjects.a 
 usr/lib/libnano-X.a 
 usr/lib/libnwidget.a 
 usr/lib/libvncauth.a