Newsgroups: comp.os.linux.announce,comp.os.linux.help From: broman@Np.nosc.mil (Vincent Broman) Subject: Linux MGR HOWTO Keywords: Linux MGR graphics window system HOWTO Followup-To: poster Approved: linux-announce@tc.cornell.edu (Matt Welsh) Archive-name: linux/howto/MGR Last-modified: 12 Jan 1994 The Linux MGR window system HOWTO Draft 12 Jan 1994 .0 This HOWTO .01 Table of Contents This HOWTO .0 What is the MGR window system? .1 Installing MGR .2 Running MGR .3 Programming for MGR .4 More Documentation .5 Credit for MGR .6 .02 Archiving This HOWTO can be found on sunsite.unc.edu in pub/Linux/docs/HOWTO. .03 Credit for the HOWTO While Vincent Broman, broman@nosc.mil, first put together this HOWTO, much of the information and text was obtained from FAQs, READMEs, etc., written by Steve Uhler, Michael Haardt, and other public-spirited net-persons. Uhler was the main architect of MGR -- see the Credit section below. .1 What is the MGR window system? MGR (ManaGeR) is a graphical window system. The MGR server provides a builtin window manager and windowed graphics terminal emulation on color and monochrome bitmap displays. MGR is controlled by mousing pop-up menus, by keyboard interaction, and by escape sequences written on pseudo-terminals by client software. MGR provides each client window with: termcap-style terminal control functions, graphics primitives such as line and circle drawing; facilities for manipulating bitmaps, fonts, icons, and pop-up menus; commands to reshape and position windows; and a message passing facility enabling client programs to rendezvous and exchange messages. Client programs may ask to be informed when a change in the window system occurs, such as a reshaped window, a pushed mouse button, or a message sent from another client program. These changes are called events. MGR notifies a client program of an event by sending it an ASCII character string in a format specified by the client program. Existing applications can be integrated into the windowing environment without modification by having MGR imitate keystrokes in response to user defined menu selections or other events. MGR currently runs on Linux, Sun 3/4 workstations with SunOS, and Coherent. Various older versions of MGR run on the Macintosh, Atari ST MiNT, Xenix, 386-Minix, DEC 3100, and the 3b1 Unix-pc. The programming interface is implemented in C and in ELisp, although supporting clients written in other languages is quite easy. Running MGR requires much less resources than X, or even gcc. It does not have the user-base or software repertory of X or MS-Windows, say, but it is quite elegant and approachable. It has been said that MGR is to X as Unix is to Multics. .2 Installing MGR You can get MGR source from ftp.thp.uni-koeln.de[134.95.64.1] in pub/linux/mgr, or on [134.95.80.1] in pub/thp/linux/mgr, if you can't reach the first site. Older versions of this distribution from Haardt can be found on tsx-11.mit.edu and elsewhere. Older versions of MGR from Uhler and others (prior to Haardt) can be found at bellcore.com:pub/mgr, although no one seems to maintain things there. MGR has been through a lot of versions and releases, but the current *Linux* version number is 0.59 until Broman installs 0.62 on bugs.nosc.mil. The version number will arrive at 1.0 when 256-color VGA code with colormap access for Linux appears. Required tools to build this distribution of MGR are m4 (GNU, or perhaps another supporting the -D option), make (GNU, or perhaps another supporting include) and groff or nroff for the docs. Also sh, awk, and POSIX install. Binary distributions have not been assembled yet, so you need an ANSI C compiler environment, e.g. gcc. A Linux installation requires Linux 0.99.10 or better, an HGC, EGA, VGA, or SVGA graphics card and a mouse. Mouses supported are: serial Microsoft mouse, serial MouseSystems 3 and 5 byte mouse, serial MMSeries mouse, serial Logitech mouse, PS/2 mouse or a bus mouse. The VGA 640x480 monochrome graphics mode is supported out of the box, as is 640x350 and 640x200. To run 800x600, or other modes supported by your BIOS and not requiring bank-switching, you need to run a small program (supplied as src/vgamisc/regs.exe) under DOS to read the VGA registers while that mode is set and write a header file which you place in the directory src/libbitblit/linux. Some VGA cards can use 128k windows, and these can run higher resolutions. Suns with SunOS 4.1.2 and bwtwo, cgthree, or cgsix frame buffers are supported. Coherent installations should refer to the README.Coh file in the source distribution. Porting the latest-and-greatest MGR to another POSIX-like system which provides select() and pty's and direct access to a bitmapped frame-buffer ought to be straightforward, just implementing the libbitblit library based on the sunmono or sunport code, say. If you want to install everything, you need 4.8 MB disk space for binaries, fonts, manual pages etc. The sources are about 2 MB, plus object files during compilation. Normally, /usr/mgr should be either the directory or a link to the directory where you install MGR stuff for runtime use. Typing "chdir /usr; gunzip < whereveryouputit/usr.tz | tar xvf -" will unpack it. The source can be put anywhere, e.g. typing "chdir /usr/src/local; gunzip < whereveryouputit/src.tz | tar xvf -" and optionally "chdir mgr/src/clients; gunzip < whereveryouputit/pbmtoprt.tz | tar xvf -" to unpack the sources from Koeln. The "readme.1st" is valuable but the "screen.gif" file is just a view of a sample desktop. The source tree can be compiled from one top-level Makefile which invokes lower-level Makefiles, all of which "include" a "Configfile" at the top level. The Configfile is created by an interactive sh script named Configure, so do something like this: chdir /usr/src/local/mgr sh ./Configure make first make depend make install make clean It might be wise, before running make, to eyeball the Configfile generated by the Configure script, checking that it looks reasonable. Several flags in MGRFLAGS can be added/omitted to change some optional features in the server, viz: -DWHO: muck utmp file so "who" works -DVI code for clicking the mouse in vi moving the cursor -DDEBUG enable debugging output selectable with -d options. -DFASTMOUSE XOR the mouse track -DBUCKEY for hot-key "mouse" commands -DPRIORITY for priority window scheduling instead of round-robin; the active window gets higher priority -DCUT for cut/paste (don't use?) -DALIGN forces window alignment for fast scrolling -DKILL kills windows upon tty i/o errors -DSHRINK use only some of the screen ($MGRSIZE in environment) -DNOSTACK don't permit event stacking -DBELL really ring the bell -DKBD read mgr input from the sun kbd, instead of stdin. This permits redirection of console msgs to a window. -DFRACCHAR fractional character movement for proportional fonts -DXMENU extended menu stuff (experimental) -DMOVIE movie making extension which logs all operations to a file for later replay -- not quite working under Linux -DEMUMIDMSBUT Emulate a missing middle mouse button by chording Not all combinations of options work on all systems. If a make complains about the lack of a default_font.h or an icon_server.h in the directory src/mgr, then just do a "make default_font.h icon_server.h" in that directory. Not all the clients are compiled and installed by the Makefiles. Directories found under src/clients with capitalized names or found packed in tar archives have problems compiling and/or running, but they may be interesting to work on. At some point check that your /etc/termcap and/or terminfo file contain entries for MGR terminals such as found in the misc directory. If all your software checks $TERMCAP in the environment, this is not needed, as long as you run set_termcap in each window. MGR works better if run setuid root, because it wants to chown ptys and write in the utmp file. This helps the ify iconifier client work better and the event passing mechanism be more secure. On Linux, root permissions are required in order to do in/out on the screen device. On other systems, you decide whether to trust it. .3 Running MGR The only file =required= in an MGR installation is the server itself. That would give you terminal emulator windows with shells running in them, but no nice clocks, extra fonts, fancy graphics, etc. Depending on options, the server needs about 150K of RAM plus dynamic space for windows, bitmaps, etc. If /usr/mgr/bin is in your PATH, then just type "mgr" to start up. When the hatched background and mouse pointer appear, hold down the left mouse button, highlight the "new window" menu item, and release the button. Then drag the mouse from corner to corner where you want a window to appear. The window will have your default shell running in it. Hold down the left mouse button over an existing window to see another menu for doing things to that window. The menu you saw that pops-up over the empty background includes the quit command. For people with a two button mouse: press both buttons together to emulate the missing middle button. ** When trying to run MGR, if you get: - can't find the screen make sure you have a /dev entry for your display device, e.g. on a Sun /dev/bwtwo0. If not, as root cd to /dev, and type "MAKEDEV bwtwo0". Otherwise, you might need the -S/dev/bwtwo0 or (Linux) the -S640x480 command line option when starting mgr. - can't get a pty make sure all of /dev/[tp]ty[pq]? are owned by root, mode 666 and all programs referenced with the "shell" option in your .mgrc startup file (if any) exist and are executable. - none but the default font, make sure MGR is looking in the right place for its fonts. Check the Configfile in the source or see whether a -f/usr/mgr/font option to mgr fixes the problem. - completely hung (not even the mouse track moves) login to your machine from another terminal (or rlogin) and kill the mgr process. A buckey-Q key will quit MGR if the keyboard still works. Sometimes you can switch to another virtual terminal with an alt-F key and kill mgr from there. .31 Applications not aware of MGR Any tty-oriented application can be run in an MGR window without further ado. Screen-oriented applications using termcap or curses can get the correct number of lines and columns by using shape(1) to reshape the window or using set_termcap(1) or set_emacs(1) to obtain the correct termcap. .32 MGR Applications (clients) distributed with the server bounce, grav, grid, hilbert, mgreyes, stringart, walk - graphics demos browse - an icon browser bury - bury this window clock - digital display of time of day clock2 - analog display of time of day close - close this window, iconify cmenu - vi menus from C compiler errors color - set the foreground and background color for text in this window cursor - change appearance of the character cursor cut - cut text from this window into the cut buffer cycle - display a sequence of icons dmgr - crude ditroff previewer fade - fade a home movie script from one scene to another font - change to a new font in this window hpmgr - hp 2621 terminal emulator ico - animate an icosahedron or other polyhedron iconmail - notification of mail arrival iconmsgs - message arrival notification ify - iconify and deiconify windows loadfont - load a font from the file system maze - a maze game mclock - micky mouse clock menu - create or select a pop-up menu mgr - bellcore window manager and server mgrbd - boulder-dash game mgrbiff - watch mailbox for mail and notify mgrload - graph of system load average mgrlock - lock the console mgrlogin - graphical login controller mgrmag - magnify a part of the screen mgrmail - notification of mail arrival mgrmode - set or clear window modes mgrmsgs - message arrival notification mgrplot - Unix "plot" graphics filter mgrsclock - sandclock mgrshowfont - browse through mgr fonts mgrsketch - a sketching/drawing program mgrview - view mgr bitmap images mless - start up less/more in separate window (broken) mvi - start up vi in a separate window (broken) oclose - (old) close a window omgrmail - (old) notification of mail arrival pbmrawtomgr - convert pbm raw bitmap to mgr bitmap format pbmstream - split out a stream of bitmaps pbmtoprt - printer output from PBM pilot - a bitmap browser resetwin - cleanup window state after client crashes messily rotate - rotate a bitmap 90 degrees. screendump - write graphics screen dump to a bitmap file set_console - redirect console messages to this window set_termcap, set_emacs - output an appropriate TERMCAP value setname - name a window, for messages and iconifying shape - reshape this window square - square this window squeeze - compress mgr bitmap using run length encoding startup - produce a skeleton startup file for current window layout texmgr - tex dvi file previewer text2font, font2text - convert between mgr font format and text unsqueeze - uncompress mgr bitmap using run length encoding window_print - print an image of a window zoom - an icon editor .33 MGR-aware clients distributed separately, see "SUPPORT" file chess - frontend to /usr/games/chess gnu emacs - editor with lisp/term/mgr.el mouse & menu support gnuplot - universal scientific data plotting metafont - font design and creation origami - folding editor pbmplus - portable bitmap format conversions, manipulations pgs - ghostscript patch and front end plplot - slick scientific data plotting ? - a groff PBM driver using Hershey fonts .4 Programming for MGR The MGR programmers manual, the C language applications interface, is found in the doc directory in troff/nroff form. It covers general concepts, the function/macro calls controlling the server, a sample application, with an index and glossary. Porting client code used with older versions of MGR sometimes requires the substitution of #include for #include and substituting or redefining BIT_XOR, BIT_AND, et al for B_XOR, B_AND, et al in the bitblt operations. Compiling client code generally requires compiler options like -I/usr/mgr/include -L/usr/mgr/lib -lmgr as well as an occasional -DOLDMGR for some dusty decks. One can get some interactive feel for the MGR server functions by reading and experimenting with the mgr.el terminal driver for GNU Emacs which implements the MGR interface library in ELisp. The usual method of inquiring state from the server has the potential of stumbling on a race condition if the client also expects a large volume of event notifications. The problem arises if an (asynchronous) event notification arrives when a (synchronous) inquiry response was expected. If this arises in practice (unusual) then the MGR state inquiry functions would have to be integrated with your event handling loop. The only major drawing function missing from the MGR protocol, it seems, is an area fill for areas other than upright rectangles. At present, the color palette itself is manipulated only by programs external to MGR. If you are thinking of hacking on the server, you can find the mouse driver in mouse.* and mouse_get.*, the grotty parts of the keyboard interface in kbd.c, and the interface to the display in the src/libbitblit/linux directory. The main procedure, much initialization, and the top level input loop are in mgr.c, and the interpretation of escape sequences is in put_window.c . .5 More documentation The programmer's manual is essential for concepts. Nearly all the clients supplied come with a man page which is installed into /usr/mgr/man/man1 or man6. Other useful man pages are bitblit.3, font.5, and bitmap.5 . There is some ambiguity in the docs in distinguishing the internal bitmap format found in your frame-buffer and the external bitmap formats found in files, e.g. icons. The mgr.1 man page covers command line options, commands in the ~/.mgrc startup file, mouse and menu interaction with the server, and hot-key shortcuts available on systems with such hot-keys. Many of the fonts in /usr/mgr/font/* are described to some extent in /usr/mgr/font/*.txt as well as in /usr/mgr/font/FONTDIR.txt, which gives X-style font descriptions for the fonts obtained in .bdf format. Font names end in WxH, where W and H are the width and height in pixels of each character box. .6 Credit for MGR Stephen Uhler, with others working at Bellcore, was the original designer and implementer of MGR, so Bellcore has copyrighted much of the code and documentation for MGR under the following conditions. * Permission is granted to copy or use this program, EXCEPT that it * may not be sold for profit, the copyright notice must be reproduced * on copies, and credit should be given to Bellcore where it is due. Other credits to: Stephen Hawley for his wonderful icons. Tommy Frandsen for the VGA linux library. Tom Heller for his Gasblit library. Andrew Haylett for the Mouse driver code. Dan McCrackin for his gasblit->linux patches. dgp@cs.nott.ac.uk for the Startrek effect fix. Alex Liu for first releasing a working Linux version of MGR. Lars Aronsson (aronsson@lysator.liu.se) for text2font and the ISO 8 bit font. Harry Pulley (hcpiv@grumpy.cis.uoguelph.ca, hcpiv@snowhite.cis.uoguelph.ca) for the Coherent port. Vance Petree & Grant Edwards & Udo Munk for their work on Hercules. Udo Munk for his work on serial mouse initialization & select. Norman Bartek & Hal Snyder at Mark Williams Co. for their help with some bugs & with Coherent device drivers. Extra thanks to Zeyd Ben Halim for lots of helpful patches, especially the adaptation of selection. Bradley Bosch for lots of patches from his 3b1 port, which fix bugs and implement new and desirable features. Andrew Morton who first wrote the cut-word code. Kapil Paranjape for the EGA support. Michael Haardt for MOVIE support fixes, bug fixes, separation of the libbitblit code into output drivers, origami folding of the code. Vincent Broman for middle mouse-button emulation, linting, Sun cgsix support, and integration of the sunport code into Haardt's layering scheme. All bitmap fonts from any source are strictly public domain in the USA. The 430 fixed-width fonts supplied with MGR were obtained from Uhler, the X distribution, Yossi Gil, and elsewhere. The Hershey vector fonts and the code for rendering them are probably freely redistributable.