Njudge
Work Guide Version 1
Guide to Working on Njudge
Table of Contents
1.Introduction 2
2.CVS 3
3.Browsing 3
4.Checkout and Checkins 3
5.Branching and Tagging 3
6.Bugzilla Bug-reporting 4
7.Classification 4
8.Lifecycle 4
9.How to report 5
10.Development Platforms 6
11.Devel.diplom 6
12.Linux 6
13.Koppix 6
14.Installation 6
15.Others 7
16.Windows 7
17.Cygwin 7
18.Development 8
19.Builds 8
20.automake/autoconf 8
21.Editing 8
22.Ide – antje 8
23.Debugging 8
24.ddd 9
25.Testing 10
26.Test script environment 10
27.One-off 10
28.Releases 11
29.Procedures 11
30.Files 11
31.Versioning 11
32.Cvs2log 11
This document is designed to be used as a guide for developers working on the Njudge project.
It is designed to be read by those whoare already familiar with the scope of the project, and are assumed to have relevant knowledge ('C' language) in any standard platform (i.e. Windows or *nix).
A general description of the njudge project can be found here.
This is the versioning system (Concurrent Versioning System) that is used to store the njudge code. For those unfamiliar with this tool the following link can be consulted to see the manual.
Setup
A specific guide to working with CVS can be found here.
You can see the current state of the CVS repository graphically, using the CVSWeb tool, here.
Files are normally checked out in the standard CVS sense, i.e. Not reserved. When ready to checkin, it is the responsibility of the person doing the chekin to ensure that the version is correct, and not overwritting any changes that a previous person may have made in the meantime. Though CVS should normally detect and warn for these situations, this is not always guanrenteed and said warnings can be ignored.
Files should only be checked in that are compile (and preferably link) clean, neither giving errors nor warnings. They should be expected to work, and not be functionally incorrect, such that a system built with the latest files should work.
All work done in CVS should normally take place in the main branch. Files versions are tagged for each release that they are used in (see Releases section below).
Branches (which in CVS are a type of tag) should only be used for interim functionality, that is not currently to be generally released, but it is important to save in CVS (for example, a new functionality that seems to work but might create problems elsewhere that are not fully investigated yet).
The Bugzilla tool is used to control the reporting of Bugs. A web interface is provided that allows bugs to be reported and controlled.
For njudge, only certain products should have bugs reported against them. These, and their associated components, are clearly documented in the Bugzilla setup itself. (Other products exist for different usages).
Bugs can have on eof a number of serverities. Though the term 'bug' is used, it actually refers to any change, be it a true defect or an enhancement request. The following types of bugs exist:
Type |
Description |
---|---|
Blocker |
A problem that prevents the software from being even being built. An absolute 'must-fix'. |
Critical |
A problem that causes severe problems (such as the judge crashing). Must be fixed before the next release. |
Major |
A problem whereby the judge can make bad ajudications, pass incorrect information to players, breach gunboat etc. Should be fixed for the next version, unless a good reason exists. |
Normal |
A problem that is normally visibile, but can be lived with, either by ignoring the situaiton or using a known work-around. |
Minor |
A problem that rarely occurs, or is not apparent to other players. |
Trivial |
Typically simple spelling mistakes or text formatting output only. |
Enhancement |
Anything that is not a 'defect' or problem, but a change. |
Bugs have the following lifecycle in Bugzilla:
State |
Description |
---|---|
NEW |
A bug's initial state, when it has been created |
ASSIGNED |
When a developer starts to work on the bug, it should be changed to this state to notify the creator and other developers (to avoid several people working to fix the same problem!) |
RESOLVED |
When the developer thinks the bug is fixed, after internal testing, it is placed in this state. |
VERIFIED |
Not normally used, intended so that the bug creator can signal that they accept that the bug has been fixed. |
CLOSED |
Not used (intended to indicate that he bug has been incorporated in a release.) |
REOPENED |
When a previsously thought resolved bug is found to be unfixed. |
UNCONFIRMED |
Not used. |
Anyone can create a bug report in Bugzilla, as long as they have previously created an account (a simple email/password combination).
The bug title should be short and indicate the type of the problem, prefixing with 'Mach:' if it is a Machivalli problem only. The full text should obviously provide information sufficient to understand and reproduce the bug (attachments can be used if necessary).
Normally, if left assigned to the default owners, it is not necessary to 'cc' the bug to anyone as normal bugs got to the judge-maint mailing list, and Machiavelli ones to [email protected].
The following list is of the existing development platforms, and indicates how they can be used.
At the time of writing, the devel.diplom machine is a SunOS SPARC platform. Developers should normally have their own account created on this machine, with a default environment suitable for compilations and test runs.
No graphical environment is available for this machine, and, due to the remote nature of the connection, sustained development effort on it may become tedious. However, it is more than adequate for simple editing and CVS operations. At a pinch, it can also be used to build the software, although it is both limited in disk and CPU power.
Linux is the standard development environment for njudge. There is no specific requirements from the system, apart from the following:
Mail Server (sendmail, exim, qmail etc.)
'C' compiler (gcc)
automake and autoconf installed (for regenerating 'configure' files)
ddd grpahical debugger for code debugging
For those unfamiliar with Linux, or wishing for a painless quick install of a system, the Knoppix distribution is highly recommended (click here for more information). It provides a bootable CD image that can be easily installed onto a spare hard-drive partition, automatically detecting most hardware configurations.
Once installed, it works as per a normal Debian distribution.
Though other documentation exists, a brief guide follows on how to set it up.
Once the initial CD has been booted, the user should invoke the command 'knx-hdinstall' from a root shell (either press 'ALT-F2' or launch a root xterm session from the KNOPPIX menu). This will prompt the user for where to install the system and what partitions to use. IT is recommended to create a swap partition of at least the size of your systems RAM, and a minimum of 3GB (preferably more) for the system itself (ext3 or reiserfs recommended system).
If you don't wish to disturb an existing boot loader (for example, Windows) make sure to generate a boot floppy when prompted to.
Note: IF, on the initial bootup, you do not get an image, it can be due to the fact that Knoppix has chosen too high a resolution for your monitor. Using the 'ALT +' key combination will allow you to cycle through other lower resolution settings.
Njudge works with other main.line distributions, with no known problems. Thouse known at present to work include:
Suse
RedHat
Mandrake
Slackware
MAC-OS has been used to a limited extented, and probably will be ok after some small changes.
Njudge has not been certified to work on a Windows platform, mainly due to the absence of a standard email send & receive mechanism. Unix 'C' functions are used, which can cause some problems when trying to build on a Windows environment.
At present, this is considered beyond the scope of this project, although Cygwin can be considered an option worth investigating.
This is a suite of programs compiled for a Windows PC to provide a complete Unix environment (including shells, compilers, linkers, debuggeres and even 'X'). njudge is known to compile on these system,s but to date no know success in actually running it has been made public.
The following section lists all the concerns for working in 'development mode' on njudge, assuming that the environment has already been created. Also, it is assumed that CVS (as previously detailed) has also been correctly configured.
Njudge has an automake/autoconf environment established. What this means, in simple terms, is that a lot of the headache of maintaining make files and automatically configured files is taken away.
By using a couple of simple configuration files, configure.ac and Makefile.am, a makefile is automatically generated as required.
At the moment, it is beyond the scope of this guide to teach how to maintain the complete automake/autoconf environment. But a simple guide follows:
The installer has an automatic script., configure, that is used to generate the make files. The normal procedure for installing a judge is thus:
./configure
--with-user=njudge --with-dir=/home/njudge/dip (or other similar
defaults)
make
make install
and then, to update an existing installation:
make upgrade
If the developer changes one of the configuration files configure.ac or Makefile.am, they have to regenerate the configuration file via:
automake; autoconf
A variety of editors exist for editing files in *nix, some examples being vi/vim and emacs. The code itself has a failry loose coding standard, which, such as it is, should try to be respected (as in terms of commenting and braces).
The author has no experience of using any IDE Integrated Development Environment) that includes code editing, building and debugging.
The standard *nix debugging tool is gdb. It is a simple tool that allows, via a command line interface, standard debugging type facilities.
Note: To make an executable suitable for debugging, it must be compiled for debugging. This can be acheived via:
make clean; make CFLAGS=''-ggdb'' upgrade
(the 'make clean' can be ommitted if code was previosuly built for debugging and only a few files have been altered)
Ddd is a GUI that sits on top of gdb, and provides a very good graphical debugging interface. It is highly recommended for those that have access to graphical capabilities and wish to properly debug the code.
There are a variety of ways of testing the njudge code, of which some are described below.
A new feature, below the 'tests' subdirectory, it allows automated testing, using preconfigured data. At the moment, use of this mechanism is still in the experiemental phase, so details will be added here later.
This is the standard mode of testing. The program to be tested (usually the ''dip'' executable) is invoked in the debugger, passing it a file that represents an email (via the -i <filename> switch). Stepping through the code will then allow it to be debugged.
A special user on the development machine, njudge@devel.diplom.org, is used to execute the build scripts.
A script, daily.sh, runs every day to try to build the latest CVS njudge snapshot. This should pick out any problems that might have occured in checkins. If successful, it will copy the snapshot build into a directory (visible on the web-site) and inform the judge-maint mailing list
A script called 'release.sh' is used to generate a release. It is passed a parameter, the version (substituting '.' for '_', i.e. Njudge-1.6.0 become njudge_1_6_0). If successful, the completed release will be made available in the ftp sub-directory.
In any release, the following special files need to be considered:
NEWS Used to say whats new about this release (normally a list of fixed bugs)
BUGS A list of the outstanding bugs, as known at time of this release
configure.ac Needs to be updated to correct version number
njudge.spec Again, to be updated to the correct version number.
Njudge versioning is currently based on the following v.m.n sequence, namely:
'v' Version, currently always '1'
'm' Major release, an incrementing number.
'n' Minor release/bug-fix, an incrementing number, reset to '0' when the major number changes.
A major release is made when essentially new functionality is added to the judge, whereas it is only considered a minor release if existing (or new) bugs were fixed.
Cvs2log is a perl script that is used to automatically generate the CHANGELOG file that lists all changes made to the source files (based on their CVS checkins). As long as reasonable comments are placed on checked in files, this tool should be useful.
Millis Miller
5th April 2004
Page