Installing Little Forms
=======================

  -- IMPORTANT: Do not install the Little Forms library system-wide as
  -- a dynamic library!  The API is not frozen yet and may break
  -- existing programs in the future!  It is also not recommended to
  -- provide it through Linux distributions until the API freezes.

    Currently to install Little Forms you just need to compile the
source code and place the generated `lforms-config' file in a location
that is accessible by the shell and makefiles.


0. Quick and dirty steps
------------------------
   These steps assume the default configuration for a system that uses
GNU Make and GNU Bash with GCC or Clang and has Python 2 installed:

     0. Make sure you have development files for X11 or Win32,
        OpenGL, Xft (X11 only) and DevIL
     1. Configure with: ./configure.py (or python2 configure.py)
     2. Build with: make
     3. Install lforms-config by copying the script to /usr/local/bin
        (or /usr/bin in MSYS2) or somewhere else widely accessible

    Now while it is being built (and probably failing to work) read the
rest of this file :-)


1. Prerequisites
----------------
    By design, Little Forms requires only the base system libraries, so
you only need the development files for those libraries.  In Windows
all C compilers should come with the necessary files.  In Linux (and
other operating systems that can use X11, such as Mac OS X and FreeBSD)
you need to install the development files for X11 (in Debian and derived
distributions you can install the package `xorg-dev' for this).

    The configuration step is done through a Python 2 script (called
`configure.py') so you need to have Python 2 installed.  Note that the
script will most likely not work with Python 3.  The script also
requires the os, sys, subprocess and optparse modules, which should be
part of the base install.  The script generates a Makefile that is meant
to be used with GNU Make (other make programs may not work, not tested)
and a `lforms-config' shell script that is meant to be used with
GNU Bash (it refers to `/bin/bash', you do not need to actually use
Bash when calling it).

    If you use OpenWatcom under Windows to build the source code you do
not need Python 2 nor GNU Make, but you will need to manually edit the
project settings in the IDE to change the default configuration.

    Beyond that you most likely will want to install the OpenGL
development files.  In Windows most C compilers should already come
with these files too.  In Linux you need to install the development
files for Mesa OpenGL (in Debian and derived distributions you can
install the package `libgl1-mesa-dev' for this -- note that if you
are using drivers that replace the OpenGL files, such as those by
Nvidia's official installer, installing this package may overwrite the
driver files and you will need to reinstall the driver).

    If you do not need OpenGL support use the `--no-opengl' flag in the
configuration step below.

    If you are building for X11 (Linux, etc) you may also want to enable
support for the Xft library.  Xft uses the FreeType library to perform
client-side font rendering with antialiasing support and - depending on
your configuration - may provide access to more fonts than if you relied
on the X server.  On the other hand, Xft will slow down a bit text
rendering, especially if you plan on using a program through SSH and X
forwarding.  To use Xft make sure its development files are installed
(in Debian and derived distributions the `xorg-dev` package mentioned
above will install the necessary development files for Xft too).

    Xft support is enabled by default when building for X11, but if you
want to disable it use the `--use-xft=no' flag in the configuration step
below.

    Little Forms also contains a few tools that convert images to source
code that can be embedded inside simple applications.  These tools
require the DevIL (aka OpenIL) image library to be available.  You can
find the library at the following web addresses:


      http://openil.sourceforge.net/ (project site)

        or

      https://github.com/DentonW/DevIL (code repository)


The tools require DevIL to be built, but they themselves are optional.
However since they are built by default they can cause the compilation
to fail.  They are built last, so you can ignore that failure.  If you
want to avoid building the tools (and thus having successful builds),
you can use the `--no-tools' flag in the configuration step below.

    Build Requirement Summary
    -------------------------
      * X11 or Win32 development files (required)
      * Python 2 (required, unless you use OpenWatcom for Windows)
      * GNU Make (required, unless you use OpenWatcom for Windows)
      * GNU Bash (required, unless you use OpenWatcom for Windows)
      * OpenGL development files (optional, recommended)
      * Xft development files (X11 only, optional)
      * DevIL development files (optional, recommended)


1. Configuration
----------------
    To prepare Little Forms for building you need to use the
`configure.py' script that will create the Makefile and `lforms-build'
script.  The configure script must be called from the source code root
directory like:

      ./configure.py [flags]

If your default Python is not 2 (which will be the case if you are using
Arch Linux or a derived distribution) you need to call it explicitly:

      python2 configure.py [flags]

    You can use a number of flags to specify how to build the library.
The currently accepted flags are:

      `--winsys=x11|win32'
        this specifies the window system that Little Forms will use as
        a backend.  The accepted values are x11 and win32 and the
        default value depends on the underlying OS.  You can override
        this for cross-compiles and building the x11 backend under
        Windows for use with an X server such as Xming.

        Example: --winsys=x11

      `--use-xft=yes|no'
        Enables or disables the use of Xft for drawing text.  The
        accepted values are yes (enable) or no (disable) and the default
        value is yes for the X11 backend and no for everything else
        (note that there is no check for the availability of the Xft
        development files so if you do not have them installed the build
        will fail).

        Enabling Xft will add a dependency to the libXft and
        libfontconfig shared object files (currently `libXft.so.2' and
        `libfontconfig.so.1') in your applications and expose a
        `LFORMS_USE_XFT' macro through the `lforms-config' script.

        Example: --use-xft=yes

      `--no-opengl'
        Disables any support for OpenGL.  Unless you plan to use the
        library for self-contained applications that only rely on X11
        you most likely do not need to specify this.  Little Forms
        programs that use OpenGL will still work but display a message
        in the windows that use the FF_OPENGL flag instead of receiving
        events to render.

        Enabling OpenGL (ie. not using this flag) will add a dependency
        to the libGL shared object (currently `libGL.so.1') in your
        applications.  Disabling OpenGL (ie. using this flag) will
        expose a  `LFORMS_NO_OPENGL' macro through the `lforms-config'
        script.

      `--no-tools'
        Disables the tool building step.  This will skip building the
        projects in the `tools' subdirectory.

      `--no-examples`
        Disables the example building step.  This will skip building
        the demo in the `demo' subdirectory and the examples in the
        `examples' subdirectory.

      `--bits=number'
        Specify the number to use for the bits flag (the `-m<number>'
        parameter) to pass to the compiler and linker.  Can be used for
        building 32bit applications in 64bit environments and
        vice-versa.

        Example: --bits=32

      `--debug'
        Create a debug build.  This enables debugging flags with the
        compiler and linker, enables debugging functionality in the
        library and causes the `lforms-config' script to expose a
        `LFORMS_DEBUG' flag.

      `--enable-sanitizers'
        Enable sanitizer flags for address, undefined and stack
        protection when building.  This flag is mainly meant to debug
        Little Forms itself.

      `--trap-x11-errors'
        By default when an X11 error occurs, Little Forms will either
        dump the X11 error request, id, etc (for debug builds) or error
        code (for release builds) and try to continue working since
        X11 errors are often not fatal.

        Enabling this flag will insert a call to `__builtin_trap()' in
        the X11 error handler, which can be used to break the execution
        inside a debugger for inspecting the program's state and find
        what caused the error.

        This flag is mainly meant to debug Little Forms itself.

      `--win32-ansi'
        When building the Win32 backend use ANSI calls instead of
        Unicode calls (e.g. CreateWindowA instead of CreateWindowW).

        Enabling Unicode (ie. not using this flag) causes adds a
        dependency on Unicode functions which may not exist in older
        versions of Windows (mainly Win9x/Me) and exposes two macros
        through `lforms-config' called `UNICODE' and `_UNICODE'.

        This is mainly useful for building applications that can work
        in old versions of Windows that do not have Unicode support
        installed by default.  Note that using this function may not
        be enough for supporting these old versions of Windows - you
        will also need to make sure that both your compiler and the C
        library it uses support these systems.

      `--devel'
        A shortcut for --use-xft=no --debug --trap-x11-errors
        --enable-sanitizers --noopengl.  As the name implies, this is
        used when developing the library itself.  Xft and OpenGL are
        disabled mainly because OpenGL drivers and Xft do not release
        allocated memory at shutdown and thus create false positives,
        making tracking real leaks and other errors reported by the
        sanitizers harder.

      `--develv'
        Like --devel but without --enable-sanitizers, used to check the
        library through Valgrind which conflicts with the Clang/GCC
        sanitizers.

An example for configure flags:

      ./configure.py --use-xft=no --debug --trap-x11-errors --no-tools

This will prepare a build for Little Forms that uses server side font
rendering, adds debugging support, will trap any X11 errors for use with
a debugger and skip building the tools.


3. Build
--------
    The build process is simple, just run `make' or `make -j' (for a
parallel build) in the source code root directory.  The Makefile exposes
the following pseudotargets:

    `all'
      Builds everything (default target)

    `tools'
      Builds the tools (make sure the dependencies are met)

    `icons'
      Creates the icon .inc files (needs the tools, note that the source
      code already comes with the inc files pre-made so this is only
      needed if you modify the icons and before doing that you need to
      remove the inc files)

    `demo'
      Builds the demo in the `demo` directory

    `examples'
      Builds the examples in the `examples' directory

    `clean'
      Removes the library and object files for a clean rebuild, however
      it keeps the Makefile and lforms-config (no need to reconfigure)

    `distclean`
      Like `clean' but also removes the Makefile and lforms-config


  -- IMPORTANT: If you want to reconfigure the library make sure you
  -- call `make distclean' before calling `./configure'.


4. Install
----------
    Currently the Little Forms API is not stable so it is not
recommended to install it system-wide.  However for single user installs
you may want to make the `lforms-config' script available.  To do that
simply copy it somewhere in your PATH, e.g. to /usr/local/bin for Linux.

    Note that if you reconfigure the library you must also reinstall the
script to avoid any configuration mismatches.
