Building and installing
Development tools and libraries alongside with their tested versions (as of this writing) are given below:
- Lua 5.1, 5.2 or 5.3
- >=libX11-1.1.3 (for the x11 driver)
- >=libXft-2.1.12 (for the x11 driver, enabled by default)
- >=fontconfig-2.5.0 (for the x11 driver, enabled by default)
- XFree86VidMode extension (for the x11 driver, disabled by default)
- >=freetype-2.3.5 (for the rawfb and directfb drivers)
- >=DirectFB-0.9.25.1 (for the directfb driver)
- LibVNCServer-0.9.9 (for the rawfb driver, disabled by default)
- libpng (for PNG support, disabled by default)
- MinGW (for building on the Windows platform)
Regarding LuaJIT 2.0 see annotations below.
TekUI does not strictly depend on any external Lua modules. The following modules are supported:
TekUI was at some point tested and should compile and run on:
- Ubuntu Linux (tested: 14.04, 9.10, 8.04, 7.10)
- FreeBSD (tested: 10.1, 8.1, 7.0), NetBSD (tested: 6.0), special precautions needed, see below
- Gentoo Linux (tested: amd64/13.0, x86/10.0, x86/2008.0, amd64/2007.0, ppc/2007.0)
- Windows (tested: 7, 2000, Wine)
- Mac OS X (tested: 10.10, XQuartz)
- Solaris (tested: 11, Sparc, x86)
- HP-UX (tested: 11.31, HPPA, IA64), special precautions needed, see below
If building fails for you, you may have to adjust the build
environment, which is located in the
config file on the topmost
directory level. Supported build tools are
gmake (common under
pmake (common under FreeBSD).
By popular request, these are the names of packages required to
compile and run tekUI on Ubuntu Linux:
On FreeBSD and NetBSD you need a Lua binary which is linked with the
-pthread option, as tekUI is using multithreaded code in shared
libraries, which are dynamically loaded by the interpreter. For
linking on NetBSD uncomment the respective section in the
file. On recent versions of FreeBSD, you will possibly want to change
the compiler to
The native Windows display driver was incomplete, slow and shabbily supported for a long time, but we have received a number of high-class contributions and spent some additional effort on this driver. It is functionally on par now and runs crisply.
For adjusting the build environment, see the
config file. We can
recommend using the MSYS shell and MinGW under Windows, or to
cross-build for Windows using GCC or clang. An example configuration
is provided in
In addition to the HP-UX settings and notes in the
you need a Lua binary with a patch for loading shared
libraries, and pthreads support. For building Lua, use
By default, libXft and fontconfig are needed for building the x11
driver. But libXft is unnecessary if you stack the rawfb driver on
top of the x11 driver. Disable it by removing
The XFree86VidMode extension is no longer linked against by default.
It can be enabled by adding
X11_DEFS in the
config file. X11 fullscreen support is problematic.
The raw framebuffer driver performs all rendering in a chunk of memory that can be supplied by a native display or the application.
It is recursive in that another tekUI display driver can be plugged into it as a visualization and input device. This was originally intended to act as a template (or skeleton) for specializations in a target context, like custom hardware or a 3D game or simulation, but it also comes in useful for providing a backbuffer for other display types.
Support for the native Linux framebuffer (and input event interface)
can be compiled into the raw framebuffer directly. It then adapts to
the active screensize and pixel format automatically. The keymap is
compiled in, by default
and can be generated using a conversion tool,
A VNC server option (through
LibVNCServer) is available
for this driver, which allows a tekUI application to be shared over
the network. This works both "headless" and with a local display. To
enable LibVNCServer support, enable the raw framebuffer and the
VNCSERVER_ defines in the config file. Note: VNC support makes
this software a combined work with LibVNCServer, see also
Any combination of the subdrivers tekUI, Linux framebuffer, and VNC is valid. If none is selected, the GUI runs isolated from the outside world, albeit in a very portable way, in its own chunk of memory.
The default configuration assumes the free fonts DejaVuSans and
DejaVuSansMono (in combination with their subtypes Bold and
Oblique) in the local directoy
tek/ui/font, but you can also
point the environment variable
FONTDIR to a
directory containing these fonts. If they are unavailable, tekUI
performs various fallbacks, including to Bitstream Vera,
which is small enough to be included in tekUI's distribution.
A mouse pointer image is loaded from
DEF_CURSORFILE, by default
tek/ui/cursor/cursor-black.png, with a fallback to a small,
built-in pointer image.
The DirectFB display driver is not very actively supported at this time. Some adaptations are likely needed. In case of problems, consider using the raw framebuffer driver, or the DirectFB driver as a rendering back-end for the raw framebuffer driver.
TekUI is free of floating point arithmetics and works with a 32bit integer version of the Lua virtual machine, with the following, noncritical exceptions:
- Support for color gradients (see
-DENABLE_GRADIENTin the config file) requires the
floatdata type in the C library.
- The desktop style needs floating point support in the Lua VM to import GTK+ colors (falls back to the default colorscheme if unavailable at runtime).
TekUI works with LuaJIT 2.0 - as long as tekUI's
multitasking interface is not used,
and possibly even then, provided that LuaJIT implements or can be
made to implement
lua_newstate() without reporting an error.
On x86_64 this has been found to not be the case. Currently the
impact of not using tekUI's multitasking API is small, and tekUI
should correctly handle the case by reporting that it could not
create a child task on LuaJIT.
To see all build targets, type
# make help
The regular build procedure is invoked with
# make all
Building a tekui executable
To build a standalone executable implementing a Lua 5.1 interpreter,
tekUI's C libraries and Lua class library, adjust
LUADISTDIR in the
config file, the exact classes to be
tek/lib/MODLIST, and invoke
# make tools
A system-wide installation of tekUI is not strictly required – in so far as the majority of display drivers is concerned. The DirectFB driver, in contrast, looks up fonts and cursors globally and must be installed in any case.
Once tekUI is built, it can be worked with and developed against, as long as you stay in the top-level directory of the distribution; all required modules and classes will be found if programs are started from there, e.g.:
If staying in the top-level directory is not desirable, then tekUI must be installed globally. By default, the installation paths are
It is not unlikely that this is different from what is common for
your operating system, distribution or development needs, so be sure
to adjust these paths in the
config file. The installation is
conveniently invoked with
# sudo make install
FONTDIR- TTF font directory for the rawfb and directfb drivers, overriding the hardcoded default (
"true"to try opening an application in fullscreen mode. Note that for this option to take effect, the application's first window must have the
RootWindowattribute set as well.
GTK2_RC_FILES- Possible locations of a gtkrc-2.0 configuration file.
"true"to disable the mouse pointer over a tekUI application. This may be useful when running on a touch screen.
THEME- Theme names corresponding to style sheet files in
tek/ui/style. Multiple themes can be separated by spaces, e.g.
"desktop gradient". The default is
"desktop". The desktop theme tries to import the color scheme found in a GTK2 configuration file. See also CSS precedence.
VNC_PORTNUMBER- Specifies a VNC server's port number.
Some properties of tekUI are configurable globally from Lua,
by modifying fields in the
ui library at program start:
ui.ExtraArgs- mostly used for hints to display drivers, one argument per line, currently supported:
fb_backbuffer=boolean- If enabled, the framebuffer driver uses a backbuffer even if not stricly needed. This can reduce flicker and sometimes improve performance, although this varies widely. Raspberry Pi, for example, was found to perform best on 16bit without backbuffer.
fb_pixfmt=hexnumber- Specify desired pixel format for the framebuffer, e.g.
include/tek/mod/visual.hfor the defines prefixed with
fb_winbackbuffer=boolean- If enabled, windows on a framebuffer use their own backing-store and do not encumber the application with refreshes when moved or otherwise exposed.
VNC_PORTNUMBER, see above
ui.FullScreen- boolean, overrides
ui.Mode- set this to
"workbench"for windows to receive buttons for dragging, resizing, closing, etc. This is intended for running tekUI in a desktop-like manner on display subsystems which do not provide a window manager.
ui.MsgFileNo- Number of the file descriptor used for dispatching lines to messages of type
MSG_USER. Default: standard input. See also the childprocess example.
NOCURSOR, see above
ui.ShortcutMark- Character to indicate that the following character is used for a keyboard shortcut. Default:
THEME, see above. See also CSS precedence.
ui.UserStyles- see CSS precedence