Building and installing

Requirements

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.

External Lua modules

TekUI does not strictly depend on any external Lua modules. The following modules are supported:

Adjusting the build environment

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 Linux) and pmake (common under FreeBSD).

Linux notes

By popular request, these are the names of packages required to compile and run tekUI on Ubuntu Linux: lua5.1, liblua5.1-0-dev, liblua5.1-filesystem0, libfreetype6-dev, libxft-dev, libxext-dev, libxxf86vm-dev.

BSD notes

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 config file. On recent versions of FreeBSD, you will possibly want to change the compiler to clang.

Windows notes

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 etc/.

HP-UX notes

In addition to the HP-UX settings and notes in the config file, you need a Lua binary with a patch for loading shared libraries, and pthreads support. For building Lua, use 

CPPFLAGS=-D_POSIX_C_SOURCE=199506L
LDFLAGS=-lpthread

X11 notes

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 -DENABLE_XFT from X11_DEFS.

The XFree86VidMode extension is no longer linked against by default. It can be enabled by adding -DENABLE_XVID to X11_DEFS in the config file. X11 fullscreen support is problematic.

Raw framebuffer notes

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 /usr/share/keymaps/i386/qwerty/us.map.gz, and can be generated using a conversion tool, etc/keymap2c.

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 src/display_rawfb/vnc/COPYING.

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.

DirectFB notes

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.

Floating point support

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_GRADIENT in the config file) requires the float data 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).

LuaJIT support

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.

Building

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 LUAARCH, LUADISTDIR in the config file, the exact classes to be included in tek/lib/MODLIST, and invoke 

# make tools

Installation

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.: 

# bin/demo.lua

If staying in the top-level directory is not desirable, then tekUI must be installed globally. By default, the installation paths are

  • /usr/local/lib/lua/5.1
  • /usr/local/share/lua/5.1

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

Environment variables

  • FONTDIR - TTF font directory for the rawfb and directfb drivers, overriding the hardcoded default (tek/ui/font)
  • FULLSCREEN - "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 RootWindow attribute set as well.
  • GTK2_RC_FILES - Possible locations of a gtkrc-2.0 configuration file.
  • NOCURSOR - "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.

Global Lua runtime arguments

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. 5650120b. See include/tek/mod/visual.h for the defines prefixed with TVPIXFMT_.
    • 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=num - Overrides VNC_PORTNUMBER, see above
  • ui.FullScreen - boolean, overrides FULLSCREEN (see above)
  • 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.
  • ui.NoCursor - Overrides NOCURSOR, see above
  • ui.ShortcutMark - Character to indicate that the following character is used for a keyboard shortcut. Default: "_"
  • ui.ThemeName - overrides THEME, see above. See also CSS precedence.
  • ui.UserStyles - see CSS precedence