kmscon/README

= KMSCON =

Kmscon is a simple terminal emulator based on linux kernel mode setting (KMS).
It is an attempt to replace the in-kernel VT implementation with a userspace
console.

== Requirements ==

  Kmscon requires the following software:
    - libudev: providing input, video, etc. device hotplug support

  Everything else is optional:

    For video output at least one of the following is required:
      - fbdev: For framebuffer video output the kernel headers must be installed
               and located in the default include path.
      - DRM: For unaccelerated drm output the "libdrm" library must be installed
             and accessible via pkg-config.
      - OpenGLES2: For accelerated video output via OpenGLESv2 the following must
                   be installed: libdrm, libgbm, egl, glesv2 (i.e., mesa)

    By default a very limited built-in keyboard handling is used. To get other
    keyboard layouts working, the following is required:
      - libxkbcommon: keyboard handling (optional but strongly recommended)
                      Without libxkbcommon, basic US-ASCII input is provided.
    libxkbcommon has no public release, yet, but is available on freedesktop.org.
    Use "--disable-xkbcommon" if you have problems due to compile-errors.

    Building libxkbcommon from Git without root:

      - You can fetch it from Git using: git clone git://anongit.freedesktop.org/xorg/lib/libxkbcommon
      - You can then ``./autogen.sh && make`` in its directory
      - You configure kmscon using:
          PKG_CONFIG_PATH="libxkbcommon/" ./configure --enable-debug --enable-xkbcommon
        assuming you cloned it into a subfolder of kmscon.

    For font handling the following is required:
      - 8x16: The 8x16 font is a static built-in font which does not require
              external dependencies.
      - freetype2: The freetype2 font uses libfreetype2 and libfontconfig to
                   provide a very basic font backend.
      - pango: drawing text with pango
               Pango requires: glib, pango, fontconfig, freetype2 and more

    For multi-seat support you need the following packages:
      - systemd: Actually only the systemd-logind daemon and library is required.

== Install ==

  To compile the kmscon binary, run the standard autotools commands:
    $ ./autogen.sh (you need this only when building from git directly)
    $ ./configure [--enable-debug] (debug-mode is strongly recommended)
    $ make
    $ make install (TODO: this is currently not supported)
  To compile the test applications, run:
    $ make check

  If you want only a very basic kmscon program without any major dependencies,
  use:
    $ ./configure --disable-debug --disable-drm --disable-xkbcommon --disable-systemd --disable-pango --disable-freetype2
  However, you will loose a lot of functionality by dropping all dependencies.

  The following configure options are available. If build-time dependencies
  cannot be satisfied, an option is automatically turned off, except if you
  explicitely enable it via command line:
    --enable-systemd: This requires the systemd-logind library to provide
                      multi-seat support for kmscon. [default: on]
    --enable-udev: This requires libudev for hotplugging support. This is
                   currently mandatory and cannot be disabled. [default: on]
    --enable-fbdev: This adds fbdev video output support. [default: on]
    --enable-drm: This adds DRM video output support. [default: on]
    --enable-gles2: This adds OpenGL hardware accelerated font rendering
                    [default: on]
    --enable-xkbcommon: Use xkbcommon for internationalized keyboard handling.
                        [default: on]
    --enable-f8x16: The 8x16 font is a static built-in fallback font
                    [default: on]
    --enable-freetype2: Uses freetype2 and fontconfig as font-backend.
                        [default: on]
    --enable-pango: Uses pango as font-backend. [default: on]
    --enable-bblit: Use simply 2D bit-blitting as renderering fallback
                    [default: on]
    --enable-debug: Enable debug mode [default: off]
    --enable-optimizations: Use GCC code optimizations [default: on]

== Running ==

  To get usage information, run:
    $ ./kmscon --help
  You can then run kmscon with:
    $ ./kmscon [options]

  For debug output use "--debug". For verbose output use "--verbose". If you
  didn't compile DRM support then you can use "--fbdev" to make kmscon select
  available framebuffer devices.

  With "--xkb-layout=<lang>" you can switch the keyboard layout.

== License ==

  This software is licensed under the terms of the MIT license. Please see
  ./COPYING for further information.

== FAQ ==

  Please see http://github.com/dvdhrm/kmscon/wiki

== Contact ==

  This software is maintained by:
    David Herrmann <dh.herrmann@googlemail.com>
  If you have any questions, do not hesitate to contact one of the maintainers.

== Code Base ==

  The kmscon code is split into several independent subsystems:
    - uterm:
      This code manages the KMS/DRI output and provides OpenGL framebuffers.
    - console:
      This draws the text on the screen and provides an API for any terminal
      emulator to visualize its contents.
    - eloop:
      Main loop implementation.
    - log:
      Log file handling.
    - unicode:
      Provides basic Unicode handling.
    - font:
      Font loading, caching and drawing operations.
    - input:
      All linux input events are captured here and converted to Unicode
      characters for input handling.
    - vt:
      The linux VT subsystem integration. This allows to run the application in
      a classic linux VT like X does.
    - vte:
      The terminal emulator library.
    - terminal:
      Connects the console, output, input and vte handling into a real terminal.
    - main:
      This connects all subsystems into a usable console application.