Overview

HTTPS SSH
                  Timetable Generation API README
                  ===============================

                         by Botond Ballo


Introduction
------------

The Timetable Generator API, also known as 'libtg', is a C++ library 
that provides access to the functionality of Timetable Generator.
Timetable Generator, available at http://botondballo.ca/timetable,
is a program that allows students at the University of Toronto to
optimize their class timetables.

The short-term goal of the Timetable Generator API is to allow
developers to write applications similar to Timetable Generator for
University of Toronto students but with different user interfaces
(for example, a web application rather than a desktop application),
without having to reimplement the core logic of the library.

The long-term goal of the Timetable Generator API is to become a
general library that can be used to generate and optimize timetables
for any university.


Licensing
---------

The Timetable Generator API is free software. It is distributed
under the GNU Lesser General Public License, version 3 or later,
with an exception to allow static linking. In a nutshell, this
means that you can write software that uses the library without
restrictions on how you can distribute such software; however,
any modifications to the library itself must be distributed under
the same license as the library. For details, please see the file
LICENSE.txt.


Requirements
------------

The Timetable Generator API is a cross-platform library. It is
known to work on Linux and Windows (the build system requires
MSYS to be installed on Windows). Other operating systems have
not been tested because the author does not have access to them;
user testing on other platforms, and patches for problems thus
discovered, are welcome.

The library is written in C++11; using it requires a C++ compiler
with sufficient C++11 feature support. The library is known to
build with GCC 5.3, GCC 6.x, and Clang 3.9. It may build with
other versions of these compilers, or other compilers, as well.

Libtg depends on three other libraries:

 1) The Boost C++ Libraries (http://www.boost.org)
    Libtg is known to work with Boost 1.63; it may work with
    other versions as well.
    In addition to using numerous header-only Boost libraries,
    libtg uses the following separately compiled Boost libraries,
    which thus have to be built to build libtg: system,
    filesystem, thread.
 2) cpp-netlib (http://cpp-netlib.github.com)
    Libtg is known to work with version 0.11.2; it may work
    with other versions as well.
 3) Botond's Collection of Common Utilities (BCCU)
    (https://bitbucket.org/botond/bccu)
    This library does not currently have version numbering.
    Use of the latest trunk is recommended.

In addition, building the library's HTML documentation requires 
additional tools to be installed; please see the next section 
for details.


Building Instructions
---------------------

Libtg's build system is written in GNU make. The library can
be built in a Unix-like environment; currently supported
environments are Linux, and MSYS on Windows. Patches adding
support for other environments are welcome. 

Building the library requires downloading the 3 libraries
described above. cpp-netlib, and the boost libraries listed
above, need to be built (preferably as static libraries);
BCCU is a header-only library. 

To allow libtg's makefile to locate the dependent libraries,
the following environment variables need to be defined when
invoking the makefile:

BOOST_ROOT     - The root directory of the Boost installation
CPPNETLIB_ROOT - The root directory of the cpp-netlib installation
BCCU_ROOT      - The root directory of the BCCU distribution

(As an alternative to defining these as environment variables,
they can be defined as arguments on the make command line,
using the VAR=value syntax). 

For boost and cpp-netlib, the libtg build system also needs
to be able to locate the compiled libraries. By default,
libtg looks for them in BOOST_ROOT/lib and CPPNETLIB_ROOT/lib,
respectively. You can override these by defining environment
variables BOOST_LIB and CPPNETLIB_LIB.

Libtg can be built in a number of different variants, with
each variant being defined by a mode (release or debug),
architecture (32-bit or 64-bit), compiler (e.g. gcc, clang),
and threading mode (single or multi).

The variant in which the library is built is controlled by
4 variables that can optionally be specified on the make
command-line. If a variable is not specified, its default
value is used:

  MODE       Valid values are 'r' (for release) and 'd' (for debug).
             The default is 'r'.

  ARCH       Valid values are '32', '64', and 'default'. 'default'
             uses the operating system's default architecture.
             The default is 'default'.

  COMPILER   Valid values are 'gcc' and 'clang'.
             The default is 'gcc'.

  THREADING  Valid values are 'single' and 'multi'.
             The default is 'multi'.
             Note that 'multi' requires support for C++11 threads,
             which some compilers (notably the official MinGW.org
             version of MinGW) do not yet have.

In addition, one can optionally provide on the make command-line
a variable named 'LIBDIR' which specifies the directory where
the built library files will be placed. 'LIBDIR' must be a
relative path and will be interpreted relative to the libtg
distribution's root directory. The default value is 'lib'.

Note that the variables 'MODE', 'ARCH', 'COMPILER', 'THREADING', 
and 'LIBDIR' can only be specified on the make command-line; 
environment variables with these named are ignored.

Finally, the library supports passing specifying extra flags to
be passed to compiler invocations (via CXXFLAGS) by using a
variable named 'EXTRA_FLAGS' on the make command line. This is
particularly useful for defining macros that alter the behaviour
of the library, of which there is currently one:

  LIBTG_PARSER_COLLECT_TIMETABLE_INSTRUCTIONS

    If defined, then during updating of timetable data the library
    will produce an additional file containing information useful
    for preparing an 'altwks.txt' file. Please refer to the "Data
    Files Used By the API" section of the documentation for details.

The makefile supports the following targets:

  all           Builds the library's main artefact, the static library
                containing libtg's functionality.
                Two variants of the static library are built, named
                'libtg.a' and 'libtgs.a' (both are placed in 'LIBDIR').
                libtgs.a contains only the object files for libtg, while
                libtg.a also bundles the object files of the dependent
                boost and cpp-netlib libraries (note: this requires that
                they be built as static rather than dynamic libraries).
                This is a convenience for users of the binary distributions
                (see 'dist' target below) who use libtg but do not 
                independently use boost and cpp-netlib, as it saves them
                the trouble of having to build boost and cpp-netlib
                themselves.

                Note: the build system does not currently support buidling 
                a shared library.

  libtg-examle  An example program demonstrating the use of libtg.

  perftest      A program that performs a time-consuming operation using
                libtg (generating timetables for a course load with a 
                very large number of possible timetables), and reports
                the performance of this operation.

  dist          Builds a binary distribution of libtg. The distribution
                contains the static library bundled with its dependencies,
                the header file used to access the API's functionality,
                the data files required to use libtg, a README, the license
                file, an example program using libtg, and a makefile to
                build the example program. It is placed in a directory
                named ../libtg-VERSION-OS-ARCH-COMPILER relative to the
                libtg root directory.

  docs          Builds the HTML documentation of libtg. Libtg's documentation
                is written using Boost QuickBook. Building the documnetation
                involves 3 steps:
                 1. Using the QuickBook tool to produce an XML file in
                    BoostBook format.
                 2. Using XSLT to produce an XML file in DocBook format.
                 3. Using XSLT to produce HTML documentation.                
                'make docs' does all this, provided the required tools are
                set up. For details on how to set them up, see the QuickBook
                documentation at www.boost.org/tools/quickbook/index.html
                In addition, libtg requires that the environment variables
                DOCBOOK_XML and DOCBOOK_XSL are defined, pointing to the
                directories where the docbook-xsl and docbook-xml tools
                (see link above) are installed. Finally, libtg requires
                access to the Boost source distribution, not just a Boost
                installation, to perform the documentation build. It looks
                for it in the location specified by the environment variable
                BOOST_SRC, falling back on BOOST_ROOT if it's not present.

  clean         Removes the built object and library files. Does not remove
                built documentation, or distribution packages.


Contact
-------

Bug reports, patches, and feature requests are welcome. Please
submit them to the public bug tracker at
https://bitbucket.org/botond/libtg/issues.

For other questions or comments, please contact the author at
botond (dot) ballo (at) mail (dot) utoronto (dot) ca.