packages/services/gfx/mw/v2_0/src/INSTALL

   1 Microwindows Installation Documentation
   2 September 6, 2001 g haerr <greg@censoft.com>
   3
   4 - For notes on Intel Assabet, see bottom of file -
   5
   6 Microwindows compiles and runs on Linux, UNIX, ELKS, MSDOS,
   7 RTEMS, X11 and bare hardware.  There is support for the MIPS,
   8 ARM, and x86 cpu's using the GNU C cross compiler.
   9
  10 Microwindows can be compiled to use different screen,
  11 mouse and keyboard drivers for a given operating system environment.
  12 Most options are set using configuration file (microwin/src/config) options.
  13 These options can be manually editted, or if running X11,
  14 by running a graphical configuration program that will read and
  15 write the config file if desired by running "make xconfig".
  16 Other options are set in the graphics drawing engine's header
  17 file microwin/src/include/device.h.
  18
  19 After changing any options in microwin/src/config, Microwindows
  20 is built by typing "make clean; make".
  21
  22 Microwindows' header files can be written to /usr/lib/microwin,
  23 and libraries to /usr/lib by typing "make install".  This
  24 is not required unless using Microwindows to build other
  25 applications, however.  All demos build using the headers
  26 and libraries built in the source tree.
  27
  28 Config options are detailed in the config file itself and
  29 following each operating environment below.  Setting the line
  30         MICROWIN=Y
  31 will build Microwindows.  The line
  32         NANOX=Y
  33 will build Nano-X.  Both are built by default.
  34
  35 Setting OPTIMIZE=Y will run an the compiler's -O switch.
  36 Setting DEBUG=Y will add -g.  Setting VERBOSE=Y will display
  37 the full compiler command line when making.  When cross-compiling
  38 for different platforms, the various XXXTOOLSPREFIX values
  39 must be set accordingly.
  40
  41 The Nano-X server can be built with a compiled-in application,
  42 or use UNIX sockets to allow seperately compiled applications
  43 to connect to the server.  Setting the line
  44         LINK_APP_INTO_SERVER=Y
  45 will build a linked application/server, which is useful for debugging
  46 and speed.  The client/server networking code has been rewritten for speed.
  47
  48 We now have support for scaled, rotated, and antialiased
  49 fonts with both truetype and adobe type 1 fonts.  To include
  50 support for truetype fonts, download freetype-1.3.1.tar.gz from
  51 either microwindows.org or www.freetype.org, and set:
  52         HAVE_FREETYPE_SUPPORT=Y
  53 in the config file. For Adobe Type 1 font support, download
  54 t1lib-1.0.tar.tz from microwindows.org or
  55 ftp://ftp.neuroinformatik.ruhr-uni-bochum.de/pub/software/t1lib/
  56 and set:
  57         HAVE_T1LIB_SUPPORT=Y
  58 in the config file.  The ftdemo and t1demo programs demonstrate
  59 use of both truetype and type 1 fonts.
  60
  61 All the demos are built in the microwin/src/bin directory.  Following
  62 are the current demos:
  63
  64 mdemo           Microwindows 3d demo
  65 mterm           Microwindows terminal emulator
  66 demo            Nano-X demo
  67 demo3           Nano-X .bmp and .jpeg display demo
  68 landmine        Nano-X landmine game
  69 world           Nano-X world graph demo
  70 nterm           Nano-X terminal emulator
  71 nclock          Nano-X clock
  72 nano-X          Nano-X server (must be run before Nano-X demo)
  73                 (see demo*.sh)
  74
  75 Linux
  76 =====
  77 Linux users set the line below in the config file.
  78         ARCH=LINUX-NATIVE
  79
  80 Linux users have the choice of running framebuffer screen drivers,
  81 which require kernel 2.2.x, the svgalib screen driver for
  82 Linux 2.0.x users, or X Windows.  The framebuffer driver runs on
  83 1, 2, 4, 8, 16 and 32bpp systems.  Both linear and VGA memory
  84 layouts are supported.  To choose between the framebuffer,
  85 svgalib driver or X Windows, (should run on all Linux systems),
  86 set one of the following lines in the config file:
  87         FRAMEBUFFER=Y           (for 1, 2, 4, 8, 16 or 32 bpp linear fb access)
  88         VGALIB=Y                (svgalib vga access)
  89         HWVGA=Y                 (hardware vga access for rtems)
  90         X11=Y                   (for X11)
  91
  92 If FRAMEBUFFER is set, the following line enables the optional
  93 4 planes VGA non-linear driver:
  94         FBVGA=Y                 (for 4 planes VGA 16 color framebuffer)
  95 For MIPS and SuperH compilations, set FBVGA=N, since system header
  96 files don't contain outb() and outw() macros.
  97
  98 When building the X11 version, it is very important to
  99 set the SCREEN_PIXTYPE value correctly, as Microwindows
 100 will emulate the target pixel depth in X11.  See the
 101 config file for more details.
 102
 103 Linux users can use either the GPM mouse driver, or a "bare"
 104 serial mouse driver that decodes the mouse directly from the
 105 serial port.  Set either line in the config file.
 106         GPMMOUSE=Y      or
 107         SERMOUSE=Y
 108         NOMOUSE=Y               (for no mouse)
 109
 110 Note that to use the GPM driver, you must start GPM with
 111 the -R option, and usually specify the mouse type with -t.
 112 See mouse.sh for an example.  If using the direct serial
 113 mouse driver, the serial port may have to be specified in
 114 microwin/src/drivers/mou_ser.c, as it defaults to /dev/ttyS1.
 115
 116 I have written a utility that converts MS fonts, for exact
 117 MS-Windows look and feel.  You must own a MS license in order
 118 to use an MS font.  To use the MS fonts, run mwin/src/fonts/convfnt32.exe
 119 on a Windows system, and it will create the win*.c font tables.
 120 Then, set the following line in the config file:
 121         HAVEMSFONTS=Y
 122
 123
 124 ELKS
 125 ====
 126 ELKS users set the line below in the config file.
 127         ARCH=ELKS
 128
 129 The NWIDGET=N line must be set, as bcc can't handle
 130 ansi C's token paste operator, used in the widget library.
 131
 132 The serial mouse driver is in microwin/src/drivers/mou_ser.c.
 133 The default mouse port and type can be changed with the following
 134 environment variables, or changed in the driver.
 135
 136 Environment Var         Default         Allowed
 137 MOUSE_TYPE              pc              ms, pc, logi(same as pc)
 138 MOUSE_PORT              /dev/ttys0      any serial port
 139
 140 It might also be a good idea to use the XOR frame-redraw window
 141 move algorithm, by setting the following lines in the config file.
 142 The XOR algorithm redraws only after the window move is
 143 completed, which works well on slower cpu's.
 144         ERASEMOVE=N
 145         UPDATEREGIONS=N
 146
 147 Since ELKS doesn't currently have a floating point library,
 148 the 3d demo is automatically compiled out of
 149 microwin/src/demos/microwin/demo.c:
 150         #define GRAPH3D 0
 151         #define IMAGE   0
 152 The IMAGE define is set to 0 as bringing in most
 153 images will break the 64k data segment limit.  The ELKS
 154 version also doesn't include the button control or wallpaper
 155 in the demo to keep the text/data sizes down.
 156
 157 The latest version of the ELKS kernel supports a variant
 158 of UNIX sockets, using numbers rather than names.  To
 159 build a client/server version of Nano-X for ELKS, the config line
 160         LINK_APP_INTO_SERVER=y
 161 must be set.  In addition, the bcc compiler doesn't support
 162 the ANSI C '##' token pasting operator which is used
 163 in the client request code, client.c.  Run the following
 164 perl script to preprocess the client.c source file:
 165
 166         cd microwin/src/nanox
 167         mv client.c client.dist
 168         ./elkspatch.pl < client.dist > client.c
 169
 170 MSDOS
 171 =====
 172 Microwindows is currently ported using MSC v5.10, and MASM.
 173 The file mcmwin.mak will build microwin.exe, and mcnanox.mak
 174 will build nanox.exe.  The DEMO= line can be changed to build
 175 different nano-X demos.
 176
 177 There are contributed DJGPP, TURBO C and PACIFIC C ports.
 178 Instructions are in microwin/src/contrib/djgpp, turboc and
 179 pacific.
 180
 181 Framebuffer notes:
 182 If you haven't used any of the Linux 2.2 framebuffer drivers before,
 183 it can be a little daunting at first. Alex Buell has written a
 184 Framebuffer HOWTO, which is available on his website at
 185 http://www.tahallah.demon.co.uk/ which goes into detail about the
 186 various drivers, command line options, and the fbset utility.
 187 For any frame buffer other than the Vesa framebuffer
 188 (which can only change modes at bootup because it needs to
 189 execute the code in the video card's ROM in real mode),
 190 you can change bits per pixel with the command 'fbset -depth {8|16|24|32}'.
 191 Another very useful framebuffer site is http://www.linux-fbdev.org
 192
 193 Intel Assabet
 194 -------------
 195 Microwindows compiles up fine on the StrongARM-based Intel
 196 Assabet.  The following information is known to work:
 197
 198 1. Kernel version - linux-2.4.0-test11
 199 2. Patches - patch-2.4.0-test11-rmk1, diff-2.4.0-test11-rmk1-np3
 200 3. Set IPAQMOUSE=Y in Microwindows' config file
 201 4. "mknod /dev/h3600_ts c 11 0" to create the touchscreen device file
 202 5. If your screen isn't calibrated, you'll have to edit the Linux kernel:
 203         - edit drivers/char/ucb1200_ts.c
 204         - search for x_rev = 0 [around line 190]
 205         - change x_rev and y_rev both to 1
 206         - recompile the kernel
 207 6. More help is available at
 208         http://www.cs.cmu.edu/~wearable/software/assabet.html
 209
 210 Have fun!
 211
 212 Greg Haerr
 213 <greg@censoft.com>