Timetable Generation API README
by Botond Ballo
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.
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
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,
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)
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
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:
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
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
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.
Bug reports, patches, and feature requests are welcome. Please
submit them to the public bug tracker at
For other questions or comments, please contact the author at
botond (dot) ballo (at) mail (dot) utoronto (dot) ca.