README

   1 = KMSCON =
   2
   3 Kmscon is a simple terminal emulator based on linux kernel mode setting (KMS).
   4 It is an attempt to replace the in-kernel VT implementation with a userspace
   5 console.
   6
   7 == Requirements ==
   8
   9   Kmscon requires the following software:
  10     - libudev: providing input, video, etc. device hotplug support
  11
  12   Everything else is optional:
  13
  14     For video output at least one of the following is required:
  15       - fbdev: For framebuffer video output the kernel headers must be installed
  16                and located in the default include path.
  17       - DRM: For unaccelerated drm output the "libdrm" library must be installed
  18              and accessible via pkg-config.
  19       - OpenGLES2: For accelerated video output via OpenGLESv2 the following must
  20                    be installed: libdrm, libgbm, egl, glesv2 (i.e., mesa)
  21
  22     By default a very limited built-in keyboard handling is used. To get other
  23     keyboard layouts working, the following is required:
  24       - libxkbcommon: keyboard handling (optional but strongly recommended)
  25                       Without libxkbcommon, basic US-ASCII input is provided.
  26     libxkbcommon has no public release, yet, but is available on freedesktop.org.
  27     Use "--disable-xkbcommon" if you have problems due to compile-errors.
  28
  29     Building libxkbcommon from Git without root:
  30
  31       - You can fetch it from Git using: git clone git://anongit.freedesktop.org/xorg/lib/libxkbcommon
  32       - You can then ``./autogen.sh && make`` in its directory
  33       - You configure kmscon using:
  34           PKG_CONFIG_PATH="libxkbcommon/" ./configure --enable-debug --enable-xkbcommon
  35         assuming you cloned it into a subfolder of kmscon.
  36
  37     For font handling the following is required:
  38       - 8x16: The 8x16 font is a static built-in font which does not require
  39               external dependencies.
  40       - freetype2: The freetype2 font uses libfreetype2 and libfontconfig to
  41                    provide a very basic font backend.
  42       - pango: drawing text with pango
  43                Pango requires: glib, pango, fontconfig, freetype2 and more
  44
  45     For multi-seat support you need the following packages:
  46       - systemd: Actually only the systemd-logind daemon and library is required.
  47
  48 == Install ==
  49
  50   To compile the kmscon binary, run the standard autotools commands:
  51     $ ./autogen.sh (you need this only when building from git directly)
  52     $ ./configure [--enable-debug] (debug-mode is strongly recommended)
  53     $ make
  54     $ make install (TODO: this is currently not supported)
  55   To compile the test applications, run:
  56     $ make check
  57
  58   If you want only a very basic kmscon program without any major dependencies,
  59   use:
  60     $ ./configure --disable-debug --disable-drm --disable-xkbcommon --disable-systemd --disable-pango --disable-freetype2
  61   However, you will loose a lot of functionality by dropping all dependencies.
  62
  63   The following configure options are available. If build-time dependencies
  64   cannot be satisfied, an option is automatically turned off, except if you
  65   explicitely enable it via command line:
  66     --enable-systemd: This requires the systemd-logind library to provide
  67                       multi-seat support for kmscon. [default: on]
  68     --enable-udev: This requires libudev for hotplugging support. This is
  69                    currently mandatory and cannot be disabled. [default: on]
  70     --enable-fbdev: This adds fbdev video output support. [default: on]
  71     --enable-drm: This adds DRM video output support. [default: on]
  72     --enable-gles2: This adds OpenGL hardware accelerated font rendering
  73                     [default: on]
  74     --enable-xkbcommon: Use xkbcommon for internationalized keyboard handling.
  75                         [default: on]
  76     --enable-f8x16: The 8x16 font is a static built-in fallback font
  77                     [default: on]
  78     --enable-freetype2: Uses freetype2 and fontconfig as font-backend.
  79                         [default: on]
  80     --enable-pango: Uses pango as font-backend. [default: on]
  81     --enable-bblit: Use simply 2D bit-blitting as renderering fallback
  82                     [default: on]
  83     --enable-debug: Enable debug mode [default: off]
  84     --enable-optimizations: Use GCC code optimizations [default: on]
  85
  86 == Running ==
  87
  88   To get usage information, run:
  89     $ ./kmscon --help
  90   You can then run kmscon with:
  91     $ ./kmscon [options]
  92
  93   For debug output use "--debug". For verbose output use "--verbose". If you
  94   didn't compile DRM support then you can use "--fbdev" to make kmscon select
  95   available framebuffer devices.
  96
  97   With "--xkb-layout=<lang>" you can switch the keyboard layout.
  98
  99 == License ==
 100
 101   This software is licensed under the terms of the MIT license. Please see
 102   ./COPYING for further information.
 103
 104 == FAQ ==
 105
 106   Please see http://github.com/dvdhrm/kmscon/wiki
 107
 108 == Contact ==
 109
 110   This software is maintained by:
 111     David Herrmann <dh.herrmann@googlemail.com>
 112   If you have any questions, do not hesitate to contact one of the maintainers.
 113
 114 == Code Base ==
 115
 116   The kmscon code is split into several independent subsystems:
 117     - uterm:
 118       This code manages the KMS/DRI output and provides OpenGL framebuffers.
 119     - console:
 120       This draws the text on the screen and provides an API for any terminal
 121       emulator to visualize its contents.
 122     - eloop:
 123       Main loop implementation.
 124     - log:
 125       Log file handling.
 126     - unicode:
 127       Provides basic Unicode handling.
 128     - font:
 129       Font loading, caching and drawing operations.
 130     - input:
 131       All linux input events are captured here and converted to Unicode
 132       characters for input handling.
 133     - vt:
 134       The linux VT subsystem integration. This allows to run the application in
 135       a classic linux VT like X does.
 136     - vte:
 137       The terminal emulator library.
 138     - terminal:
 139       Connects the console, output, input and vte handling into a real terminal.
 140     - main:
 141       This connects all subsystems into a usable console application.