FET (c) 2002-2010 Liviu Lalescu


Program description:

	FET is free timetabling software (licensed under GNU GPL).
	This program aims to automatically generate the timetable of a school, high-school or university.
	It may be used for other timetabling purposes.

	FET can mean "Free Educational Timetabling" (the "E" in the middle may also stand for other words, based on your personal preference).

	FET homepage: http://lalescu.ro/liviu/fet/


Requirements:

	FET is created in the following environment: openSUSE 11.2 GNU/Linux distribution,
	Midnight Commander 4.6.2, Qt 4.6.2, gcc 4.4.2, Linux 2.6.31, KDiff3 0.9.95, other great free tools.
	FET can be run on any platform supported by the free software Qt (GNU/Linux, Windows, Mac OS X).

	GNU/Linux, Mac OS X and similar OS's:
	Software:
		make (GNU make command)
		gcc 4.4.2 or similar
		gcc-c++ (or g++, the name may vary)
		Qt 4.6.2 or compatible
		
	Microsoft Windows:
	For running, you need only the archive of FET compiled for Windows (which contains the MinGW and Qt dlls).
	For compiling, you need Qt and a compatible C++ compiler (MinGW is probably an easy option).


Download:

	You can download the latest version from the FET homepage, http://lalescu.ro/liviu/fet/

	Older versions: you may find some older versions on the FET homepage. If you are interested in all the older
	versions, you will have to contact the author.


Getting - compiling - installing GNU tools: make, gcc and gcc-c++ (or g++):

	GNU/Linux, Mac OS X: Most probably, your platform has these installed by default or available on the internet
	as precompiled packages. If you don't have them, please install them using YaST (on openSUSE), Adept Manager
	(on Ubuntu or Kubuntu) or other package manager.
	To verify that you have the correct packages, write "make --version", "gcc --version" and
	"g++ --version".
	
	Windows: you need a Qt compatible C++ compiler
	(maybe the easiest option the MinGW compiler, which is installed automatically by Qt) (see below)


Getting - compiling - installing Qt by Nokia:

	You will need Qt 4.6.2 or compatible to compile FET.
	You can get the corresponding version of Qt with your package manager or from http://qt.nokia.com/
	Qt can be downloaded with LGPL (open source) or commercial license, complete SDK or Framework only. Any variant should work.
	
	GNU/Linux: It is possible to use YaST (or Adept Manager) or other package managers to get your version of Qt, pre-compiled.
	Or you can download, compile and install Qt from http://qt.nokia.com/ .
	On my OpenSUSE GNU/Linux, which has pre-compiled packages on the internet, I need to install the packages
	libqt4 and libqt4-devel (libqt4 is installed by default, I think) - to compile+run FET.
	For Ubuntu GNU/Linux (advice from a user):
	sudo apt-get install qt4-qmake
	sudo apt-get build-dep qt4-qmake
	sudo apt-get install libqt4-dev
	sudo apt-get build-dep libqt4-dev
	
	Windows - Download latest Qt from http://qt.nokia.com/
	If you choose the LGPL Qt for MinGW: get Qt LGPL complete SDK and let Qt install also MinGW, or get Qt LGPL Framework only
	and download and install MinGW from the MinGW homepage.
	The following instructions are for Qt LGPL complete SDK for MinGW:
	If you use the Windows command prompt:
	Please make sure, after installing Qt and MinGW, that you have in the PATH environment variable
	the path to qmake.exe (for Qt 4.6.2 SDK it is: C:\Qt\2010.02.1\qt\bin) and for mingw (C:\Qt\2010.02.1\mingw\bin).
	Additionally (if you get a message that the platform or QMAKESPEC is not set), you may need to set an environment variable QMAKESPEC = win32-g++
	(in this case see also the note below about QMAKESPEC environment variable).
	If the above is not enough, you may need to add an environment variable QTDIR = C:\Qt\2010.02.1\qt
	If this is again not sufficient, you may need to add in the PATH the directory C:\Qt\2010.02.1\bin (this step is unverified).
	You may want to use the Qt command prompt, in which case you don't need to care about the details above (PATH, QMAKESPEC and QTDIR).
	
	Mac OS X:
	Maybe you can get pre-compiled Qt packages for Mac OS X. If not, get Qt from http://qt.nokia.com/

	Note about the Qt "QMAKESPEC" variable: advanced topic, read this if you get Qt errors about the environment not being set, or environment
	variable QMAKESPEC not being set, or if the Qt environment is not set correctly: Qt needs to know the environment you are using. It is usually
	something like: linux-g++, macx-g++ or win32-g++ (platform-compiler). You can find all the supported platforms in the directory "mkspecs" of Qt
	(some usual locations are /usr/share/qt4/mkspecs or /usr/lib/qt4/mkspecs on GNU/Linux or C:\Qt\2010.02.1\qt\mkspecs on Windows).
	It seems that Qt automatically finds the platform (there is a default configuration in the "default" subdirectory of the "mkspecs" directory,
	which is created automatically when you install Qt). If the default configuration is not working or is wrong, you may need to set the
	correct QMAKESPEC variable for your platform. Under Windows, you can create an environment variable QMAKESPEC equal to win32-g++
	(if you are using MinGW), under other platforms create an environment variable named QMAKESPEC equal with the correct platform-compiler
	you are working on (for instance macx-g++ or linux-g++).


Compiling FET:

	Note: compilation takes long (maybe even 1 hour, if you are using an older computer). The file
	rules.cpp takes the longest time to compile, maybe even 1 minute or more.
	
	Note2: the following situation may appear under GNU/Linux, but it could be met also on other platforms.
	Depending on your Qt installation, it may happen that the FET intermediary files and executable are very large
	(~100 MB for the fet executable instead of ~10 MB). I am not sure if this affects the FET speed and performance, but anyway it is
	unpleasant. In this case, you may want to modify some files in your system (Qt files) to improve this. You need to change some Qt configuration
	files and recompile FET from the beginning (remove any temporary files with make distclean or unpack FET sources again, in an empty location).
	Notations: mkspecs is a directory and QMAKE_CFLAGS_RELEASE is a section (text on a line) contained in a file in a subdirectory of mkspecs.
	(some possible location for these are given in this paragraph, shortly below).
	If mkspecs files for your platform contain the -g flag (text) in the QMAKE_CFLAGS_RELEASE section, you need to remove this flag from this section.
	If they do not contain -g flag in this section, then you don't need to remove anything (and most probably the intermediary files and fet
	executable will have normal size).
	More details about where can you find the mkspecs files: under my openSUSE GNU/Linux, I need to modify the /usr/share/qt4/mkspecs/common/g++.conf,
	line 10, remove the "-g" flag from the QMAKE_CFLAGS_RELEASE section (root access needed to make this change).
	Under Fedora GNU/Linux for the same problem, a user reported that you need to modify /usr/lib/qt4/mkspecs/common/g++.conf
	and /usr/lib/qt4/mkspecs/linux-g++/qmake.conf (remove the -g flag from QMAKE_CFLAGS_RELEASE section).
	(Do not confound the section QMAKE_CFLAGS_RELEASE with QMAKE_CFLAGS_DEBUG. It is normal for the section QMAKE_CFLAGS_DEBUG to
	contain the -g flag, because it is for debug, not release, so in the debug section leave it unchanged).
	(The mkspecs directory contains more subdirectories, in the form platform-compiler, you need to search for your corresponding directories/files.
	For instance, GNU/Linux with gcc compiler is named "linux-g++", and you may also need to modify the "common" section).
	
	Currently FET can be compiled with a C++ compiler, using Qt version 4.6.2 or compatible.


	GNU/Linux and similar OS's:
	- You will need Qt 4.6.2 or compatible to compile this program.
	- type "qmake fet.pro" or simply "qmake". You have to use qmake from Qt 4 series, which on some systems
	might be named qmake-qt4 (this command is executed very fast, so don't worry if you get immediate return from it)
	- type "make" (this takes a long time, maybe even 1 hour)
	To remove the compiled objects/executable: "make clean" and/or "make distclean".
	
	
	Mac OS X:
	2 Variants:
	
	1. First variant, if you use gcc compiler:
	- You will need Qt 4.6.2 or compatible to compile this program.
	- type "qmake fet.pro" or simply "qmake". You have to use qmake from Qt 4 series, which on some systems
	might be named qmake-qt4. So, "qmake-qt4 fet.pro" might sometimes be needed.
	(this command is executed very fast, so don't worry if you get immediate return from it)
	- IMPORTANT: you might need to write: "qmake -spec macx-g++ fet.pro", if "qmake fet.pro" 
	does not produce a correct makefile. Please see 
	http://lists.trolltech.com/qt-interest/2007-04/thread01126-0.html for details.
	- type "make" (this takes a long time, maybe even 1 hour)
	To remove the compiled objects/executable: "make clean" and/or "make distclean".
	
	2. Another variant:
	- Type "qmake fet.pro" and then "xcodebuild".
	
	If you encounter problems, please see:
	http://lists.trolltech.com/qt-interest/2007-04/thread01126-0.html

	
	Microsoft Windows: MinGW C++ compiler: you need Qt 4.6.2 (2010.02.1) or compatible.
	You will have to download and install Qt with MinGW from http://qt.nokia.com/ .
	You might use other compilers if you want, please see the Qt web page http://qt.nokia.com/
	for other variants. Any C++ compiler that supports Qt should be good.
	You need to run "qmake fet.pro" or "qmake" (this command is executed very fast, so don't worry if you get
	immediate return from it) and then "mingw32-make" (this takes a long time, maybe even 1 hour) 
	in a command line in the FET directory.
	(You can use the command line prompt of Windows or use the Qt command line prompt
	shortcut in the Qt shortcuts menu.)
	Then, you can remove directories "src" and "tmp", to save up space, if you want.
	For MinGW:
	If you don't have Qt directory in the path and get messages about missing dll-s when trying to run fet.exe, or
	if you want to obtain a version which can be run on other computers,
	you have to copy these 8 files into the FET directory (in the same place as fet.exe):
	(QTDIR is an abbreviation for C:\Qt\2010.02.1\qt if you use Qt SDK 2010.02.1, which is based on/contains Qt version 4.6.2)
	QTDIR\bin\mingwm10.dll, QTDIR\bin\libgcc_s_dw2-1.dll,
	QTDIR\bin\Qt3Support4.dll, QTDIR\bin\QtCore4.dll, QTDIR\bin\QtGui4.dll,
	QTDIR\bin\QtNetwork4.dll, QTDIR\bin\QtSQl4.dll, QTDIR\bin\QtXml4.dll.
	
	
Installing FET:

	GNU/Linux and similar OS's:
	Please move the whole directory "fet-x.x.x" into the place where you like,
	for instance to the directory "/usr/local/".
	
	Microsoft Windows:
	Move the FET directory in a place of your choice.


Running FET:
	Note: The FET main window contains a menu with the items: File, Data, Statistics, Advanced,
	Timetable, Settings, Help. Everything is right if you have that. Optionally, on the main window there may be a toolbox
	containing shortcuts (if selected by the user in the settings. By default it is selected).
	
	Note: to run FET in interface mode, you just need to run the executable named fet or fet.exe.
	No additional parameters are needed/allowed. If you give additional parameters, FET will
	consider that you want to run the command line version (see below instructions for command line version).

	GNU/Linux and similar OS's:
	chdir to the directory where the fet executable is (for instance, "cd /home/liviu/fet-x.x.x/") and run it with "./fet" or with the suitable command
	for your platform. Alternatively, you may run the executable named fet from the fet-x.x.x directory, using another method. The fet executable
	will be located inside the fet-x.x.x directory after a successful compilation.
	
	Note for Mac OS X about using translations (if you want to run FET into other language): it seems that you need to copy the contents
	of the "translations/" directory into the directory fet-x.x.x/fet.app/Contents/MacOS/translations/ or into the directory /usr/share/fet/translations/
	(if you compiled/installed FET by yourself).
	
	Microsoft Windows:
	Run the executable fet.exe (its location is inside the fet-x.x.x directory, you can find it there if you have FET precompiled for Windows or after you compiled it).
	
	COMMAND LINE: no GUI, just run "fet --inputfile=x [--outputdir=d] [--timelimitseconds=y] [--htmllevel=z] [--language=t] [--printnotavailable=u] [--printbreak=b]
	 [--dividetimeaxisbydays=v] [--printsimultaneousactivities=w] [--randomseed=r] [--warnifusingnotperfectconstraints=s] [--warnifusingstudentsminhoursdailywithallowemptydays=p]",
	where	x is the input file, for instance "data.fet"
			d is the path to results directory, without trailing slash or backslash (default is current working path).
				Make sure you have write permissions there.
			y is integer (seconds) (default 2000000000, which is practically infinite).
			z is integer from 0 to 6 and represents the detail level for the generated html timetables
				(default 2, larger values have more details/facilities and larger file sizes).
			t is one of en_US, ar, ca, da, de, el, es, fa, fr, hu, id, it, lt, mk, ms, nl, pl, pt_BR, ro, ru, si, tr, uk (default en_US).
			u is either "true" or "false" and represents if you want -x- (for true) or --- (for false) in the generated timetables for the
				not available slots (default true).
			b is either "true" or "false" and represents if you want -X- (for true) or --- (for false) in the generated timetables for the
				break slots (default true).
			v is either true or false, represents if you want html timetables with time-axis divided by days (default false).
			w is either true or false, represents if you want html timetables to show related activities which have constraints with same starting time (default false).
				(for instance, if A1 (T1, G1) and A2 (T2, G2) have constraint activities same starting time, then in T1's timetable will appear also A2, at the same slot
				as A1).
			r is the random seed, minimum 1 to maximum 2147483646 (you can get the same timetable if the input file is identical and if the random seed is the same).
			s is either true or false, represents whether you want a message box to be shown, with a warning, if the input file contains not perfect constraints
				(activity tag max hours daily or students max gaps per day) (default true).
			p is either true or false, represents whether you want a message box to be shown, with a warning, if the input file contains non standard constraints
				students min hours daily with allow empty days (default true).
				
	Alternatively, you can run "fet --version [--outputdir=d]" to get the current FET version.
	where	d is the path to results directory, without trailing slash or backslash (default is current working path).
				Make sure you have write permissions there.
	(If you specify the "--version" argument, FET just prints version number on the command line prompt and in the output directory and exits.)
	
	The result of the operation is logged into file outputdir/logs/result.txt.
	
	Also, you have in logs the initial order of activities and a list of maximum placed number of activities. If your timetable is impossible, say it stops
	at maximum n placed activities, look at the n+1-st activity in the initial order, for it or its students/teachers may be the problem.
		
	For the command line version, probably the most useful output to use internally in an application might be the activities_timetable.xml.
	You have of course also the xml timetables for students and teachers and the nicely formatted html timetables to present directly.
			
	On GNU/Linux and Mac OS X, you'll get a console output to help you with data, along with the files in the directory outputdir/logs/.
	
	On Windows, there is no console output, only the files in the directory outputdir\logs\ will guide you,
	I cannot make a console output on Windows (I could, but it would complicate the interface).
	

Languages (translations):

	The translation files which the FET executable needs in order to be able to run in other languages are ending in .qm (like fet_xx.qm)
	and they are located in the "translations" directory in the FET distribution.
	
	FET will search for translations (fet_xx.qm files) in the following order:
	1) directly in the directory where the fet executable is,
	2) the directory "translations" in the directory where fet executable is,
	3) the directory /usr/share/fet/translations (under GNU/Linux or Mac OS X).
	
	So, on:
	Windows: if fet.exe is in C:\fet-x.x.x, fet will search for the file fet_xx.qm in
		C:\fet-x.x.x and then in C:\fet-x.x.x\translations
	GNU/Linux: if the fet executable is in /home/liviu/fet-x.x.x, fet will search for the file fet_xx.qm in
		/home/liviu/fet-x.x.x, then in /home/liviu/fet-x.x.x/translations and then in /usr/share/fet/translations
	Mac OS X: the operation is approximately similar to GNU/Linux.
		The difference is that it seems that the fet application on Mac OS X contains in turn other directories (application directories),
		so FET will search for the translations inside these application directories, not in the fet-x.x.x directory. The GNU/Linux style fet executable
		seems to be located in fet-x.x.x/fet.app/Contents/MacOS, so FET will search for the file fet_xx.qm in the directory
		fet-x.x.x/fet.app/Contents/MacOS, then in the directory fet-x.x.x/fet.app/Contents/MacOS/translations,
		then in the directory /usr/share/fet/translations.
		Please see also the Mac OS X note from the section "Running FET".
	
	
Documentation:

	Some hints in the directory "fet-x.x.x/doc/".
	Some other hints in the Help menu.
	You may find more documentation on the FET homepage.


Input files:

	You can open a few sample input files in "fet-x.x.x/examples/" directory
	(under GNU/Linux or Mac OS X, they may be found in /usr/share/doc/fet/, or /usr/share/fet/)
	
	You can create/modify a file from FET's user interface or you can modify it by
	hand, if you like.


Un-installing FET:

	Remove the directory fet-x.x.x. Also, you may want to remove the directory with the fet results (default: $HOME/fet-results).
	This will leave the settings of FET on your system, certainly this is not a problem.
	FET stores a few bytes in your operating system settings. If you really want to get rid of everything FET created, read below.

	To remove the FET settings from your operating system (unnecessary step):
	
	GNU/Linux and similar OS's:
	Probably in $HOME/.config directory you'll find a directory "fet" containing file "fettimetabling.conf". Remove the file and the directory.
	
	Microsoft Windows:
	Run regedit, search key "fet". You will find a section "fet" with sub-section "fettimetabling". Remove it.


Feed-back / help:
	- I would like to hear your oppinions/results about this program; any feed-back would be greatly appreciated.
	- You are encouraged to send your data files, for the purpose of testing or for inclusion into examples. Contact the author for that or write on the forum.
	- Reporting bugs/wishes/patches: to forum, mailing list or author.
	
	This project is free software, so any sponsoring offer/donation would be great. You can contact the author for that. Alternatively, you can contact
	a contributor or a translator.
