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.