![]() | KGoldrunner - Technical Details |
HOME | Previous Installation This section is aimed at programmers who wish to work on KGoldrunner as a developer or port it to other operating systems and desktops. Before starting, please contact the authors, to make sure you have the latest versions of the distribution files (email addresses are in the "Help, About KGoldrunner" menu option message). Also, have a look at the Installation section of this document. Compiling and Building KGoldrunner as a DeveloperThe Installation section describes how to install KGoldrunner into the KDE system directories. To install it into your own area, proceed similarly, but log in as yourself, use one of your own working directories and omit the "make install" command.If you are familiar with the KDevelop IDE (Integrated Development Environment), there is a "kgoldrunner.kdevprj" project definition file in the "kgoldrunner-V-kdeN" directory (where V is the KGoldrunner version and N is 1 or 2). Accessing the Documentation and Games Data FilesYou will find the English documentation files in "kgoldrunner-V-kdeN/kgoldrunner/docs/en" and the games data files in "kgoldrunner-V-kdeN/kgoldrunner/system".Among the games data files is one called "levels.tar". If you need to add to the released levels, use the command "tar xf levels.tar" to unpack the levels files into sub-directory "levels". Repack them using the command "tar cf levels.tar levels". The text-file "games.dat" will also need to be edited or replaced. It contains a summary of the files in the "levels" directory (prefixes and counts) and it must be consistent. When you run KGoldrunner, you will normally access the levels files and documentation installed in the KDE system. For most purposes it will be enough to keep new games and levels in the User area KGoldrunner already provides, while you are editing and testing them. The relevant files are saved in your home directory structure in ".kde/share/apps/kgoldrun" in KDE 1 or ".kde2/share/apps/kgoldrun/user" in KDE 2. If you are changing the documentation, you can access your development version from KGoldrunner by typing in the full path the first time, then saving it as a bookmark. If you have to access the copies of System games data and levels in your development area, you will need to mimic the KDE "share/apps" directory structure somewhere in your directory area. Either copy or preferably link the games and levels sub-directories into that structure at the correct point. Now, in KDE 1, you execute KGoldrunner with KDEDIR temporarily defined to your structure's base, e.g.:
KDEDIR=$HOME/mydir ./kgoldrunner In KDE 2, there is no KDEDIR, but there is a "path" variable KDEDIRS for finding application data files. Set it by using:
export KDEDIRS=$HOME/mydir:$KDEDIRS then you can simply use "./kgoldrunner" to execute. Keeping Versions in SyncPlease note that there is really only one set of source files, graphics files, games files, levels files and documentation for KGoldrunner, even though it is distributed as two sets, one for KDE 1 and one for KDE 2. Only the "make", "configuration" and "project" files are different. So if you change anything, please make certain that it is changed in both distributions.Also, only the KDE 2 version contains the CVS (Concurrent Version control) repositories and you should "commit" all your changes to them when you finish your work. Makefiles, KDevelop, "automake" and "autoconf"When you install KGoldrunner, each directory in the uncompressed distribution files has "Makefile"s which contain specifications for compiling, building and installing the software and files, but these "Makefile"s have been generated by the "./configure" script and are tailored to fit your system. Therefore you should not edit and re-distribute the "Makefile"s, even if you know how!The best approach is to use KDevelop, which generates all the right files for each directory in your project and allows you to "register" new files for compilation, distribution or installation, whereupon references to them get incorporated into the generated files. The files generated by KDevelop are "Makefile.am", "Makefile.in" and "Makefile" in each project directory and "configure.in", "acinclude.m4", "aclocal.m4" and "configure" in the top directory. All of these, except for "Makefile", are distributed. The base files are "Makefile.am" and "configure.in". If you want to add to the rules KDevelop generates automatically, these are the files you need to change, but avoid the sections between comments that KDevelop overwrites. The released "Makefile.am" files contain a few such changes, e.g. to implement "make init", to unpack the levels after "levels.tar" has been installed and to uninstall the levels files and "kgoldrun" directories. KDevelop uses "automake" to generate "Makefile.in" files from "Makefile.am" and "autoconf" to generate the "configure" script from "config.in", then it uses the "configure" script to generate "Makefile" from "Makefile.in". If you wish, you can do these steps yourself, provided you start by changing only "Makefile.am" and "config.in". Where to Find KDevelop, "automake" and "autoconf"KDevelop, "automake" and "autoconf" are (or should be) packages in your Linux distribution. When you install the KDevelop package, "automake" and "autoconf" are installed automatically (or should be). Once installed, KDevelop has extensive and readable built-in documentation.When "automake" and "autoconf" are installed, the documentation can be found in the "info" documentation browser, which also has a very good writeup on "Make" (a "must read", if you are going to make much sense of the "automake" and "autoconf" documents). Also in "info", see "Standards" (section "Managing Releases", sub-sections "Configuration" and "Makefile Conventions") for further background information. Portability ConcernsIn KDE 1, KGoldrunner is heavily dependent on KDE object and GUI libraries and so is not portable.In KDE 2, there is just one procedure, "getDirectories", that depends on KDE. It locates the directories where the documentation, games and levels are stored. Everything else depends only on Qt 2 and C++ and so should be portable to other operating systems. To assist portability further, most file names have been kept down to 8 characters (alphanumeric and underscore only) and file extensions have been kept down to 3 characters (e.g. ".htm" for documentation, rather than ".html"). Compilation ConcernsWhen changing from KDE 1 to KDE 2, the KDE libraries introduced source-code incompatibilities and so did the Qt library when going from Qt 1 to Qt 2. This meant that the definitions of some classes changed and source code depending on those classes had to change too. KGoldrunner v1.0 has source code that can be compiled either with KDE 1 and Qt 1 or with KDE 2 and Qt 2. Dual compilation depends on three approaches:
The script requires a string parameter that ends in "kde1" or "kde2". In the "make init" rule, which runs "fix_src", this parameter is supplied by the Makefile's VERSION variable, as set up in the KDevelop project definition (e.g. "1.0-kde1" or "1.0-kde2"). Danger: Software InterruptsKGoldrunner is controlled by outside events, such as timer events, mouse clicks, keystrokes and window management actions. Any of these can happen at any moment, depending on the whims of the user and the demands of the animation. Qt also has a very handy "signal and slot" mechanism, which is used extensively in KGoldrunner.Ordinarily, Qt will not execute event-handling procedures and slots until you return from the current procedure and Qt resumes control (i.e. events are queued). There are however some cases where an event-handler or slot can be executed unexpectedly, between two lines of source code. If it changes data items or objects you are currently accessing, some very weird and hard-to-find bugs can result, ranging from the hero running amok to a full-on "Segmentation Fault" crash. The following are cases where this kind of thing can happen:
The Main Modules of KGoldrunner
The "games.dat" File FormatThe "games.dat" files are stored in the KGoldrunner System and User data area, as documented in the Installation section and above. The file in the System area lists System games and the file in the User area (if any) lists games belonging to the logged in user.Each game in each file is represented by one line or two lines of text. The second line is optional and contains a description of the game, that is displayed by clicking the "More" button in the Level Selection Dialog box. The text is automatically word-wrapped when it is displayed. Paragraph breaks are represented by the characters "\n\n" (i.e. the "newline" characters as represented in C and C++). The first (maybe the only) line contains four fields, separated by a space, as follows:
The "levels" File FormatLevels files are all stored in the "levels" sub-directory in the KGoldrunner System or User data area, as documented in the Installation section and above. They all have names of the form "prefixNNN.grl", where "prefix" is the game's filename prefix (e.g. "tute" or "plws") and NNN is a 3-digit level number (e.g. "tute008.grl" is level 8 of the Tutorial game). Level numbers should always start at 001 and be consecutive, up to the number of levels in the game. If they are not, KGoldrunner will issue a warning message.An exception is the special file "level000.grl", which must be present in the System levels sub-directory. It contains the "ENDE" screen, which appears when the game is over ("ENDE" is German for "END"). Each level file is a text-file, containing one or more lines as follows:
The High-Score File FormatReleased high-score files for the System games are stored in the System data area, but are "read-only". The System file for high scores in a game is copied to the User data area and the user's high score is added, whenever the user first achieves a high score for that game. After that, all high scores achieved are added to the User copy of the high-score file. High-score file names are of the form "hi_prefix.dat", where "prefix" is the game's filename prefix (e.g. "tute" or "plws").The file is recorded in the portable binary data format implemented by the Qt library's QDataStream class. There are up to 10 records, in descending order of score achieved, and each record contains four fields as follows:
The Saved-Game File FormatThe saved game file is stored in the User data area and its name is "savegame.dat". It is a text file, with one line per save, and up to 30 game positions can be saved. The most recent save is first and the oldest is last. Each line contains seven formatted columns as follows:
HOME | Previous Installation |