Install
Just do the usual ./configure; make; make install Of course you need the GGI libraries installed, and optionnally freetype. Well, if you don't have freetype you lose much of the ggiterm reason for being, but it could still be useful for embedded use... If you have the libggiwmh extension installed, ggiterm will use it to display the app's name in the window's title bar instead the the default title. This is useful only on windowed targets, like X-Window or Windows.
Post-install
For ggiterm to function properly, you must add the ggiterm entry to your system's terminal capabilities database. Depending on your system, you will have to either (as root):
- run the command "tic ggiterm.terminfo"
- add the contents of ggiterm.termcap to your termcap file (or edit the existing entry)
NOTE: if you are upgrading from version <= 0.6.2, don't overlook this step! The
ggiterm entry has been significantly reworked for 0.7.0, and using an old
entry with a newer version can give unexpected results...
Running ggiterm
CAVEAT: ggiterm has been tested only at color depths >= 8.
ggiterm --help will tell you about the available runtime arguments. Without specifying any, you will be stuck with the default rendering options, which won't be very impressive: plain ASCII, the default GGI font, etc...
Setting the --font option to your preferred * FIXED WIDTH * True Type font will
give much better results!
I suggest Microsoft Courier New (widely available), or monofur from Tobias
Kohler (much more fun and available for free at http://www.dafont.com).
Both have graphical drawing characters and allow underlining. Another great
font I found recently is Fixedsys Excelsior (http://www.fixedsys.org).
If you get a message like "Unknown terminal type" when running a terminal-based application (vi, emacs, ...) from within ggiterm, this is because your host doesn't have a ggiterm entry in its terminal capabilities database (see Post-Install section). In this case, setting the TERM environment variable to "vt100" prior to launching your application will allow it to run, however with reduced features (eg. no colors).
Framebuffer
If you run ggiterm on a framebuffer-like target, make sure the current mode leaves enough video memory to hold a virtual screen twice as big as the visible area. Otherwise ggiterm will not be able to scroll with ggiSetOrigin() and will fall back to ggiCopyBox(), which is unbearably slow on unaccelerated targets.
The math is simple: a 1024x768 framebuffer with 16 bits color depth uses up 1024 x 768 x 2 = 1572864 bytes of memory (1.5 Mb). So in this case you need at least 3 Mb of video memory to get a decent speed.
Known bugs
You may notice a little flickering during scrolling operations under the X
target. This is because offscreen contents are not cached by the X server and
have to be retrieved from the GGI backbuffer each time ggiterm reaches the
bottom of its virtual screen.
Maybe one day GGI will provide an option to enable backing store, but for now
you have to manually tell the X server to do it by default.
For X.org or XFree86 this can be done with the +bs option:
$ startx -- +bs
or specify
/usr/X11R6/bin/X +bs
as the X server in your graphical login manager (xdm, gdm, kdm, etc...)
Troubleshooting
ggiterm is built by default without debugging support. If anything goes wrong, recompile with ./configure --enable-debug, and run ggiterm with --debuglevel set to the relevant value (see man page). Be warned, the log can be HUGE, so it is recommended to redirect the output to a file in order to get a decent speed. Then email me the debugging output with a description of the problem, I'll try to fix it.