Guide to Working on Njudge

1. Introduction

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.

2. CVS

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.

3. Browsing

You can see the current state of the CVS repository graphically, using the CVSWeb tool, here.

4. Checkout and Checkins

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.

5. Branching and Tagging

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).

6. Bugzilla Bug-reporting

The Bugzilla tool is used to control the reporting of Bugs. A web interface is provided that allows bugs to be reported and controlled.

7. Classification

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:

8. Lifecycle

Bugs have the following lifecycle in Bugzilla:

9. How to report

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].

10. Development Platforms

The following list is of the existing development platforms, and indicates how they can be used.

11. Devel.diplom

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.

12. Linux

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

13. Koppix

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.

14. Installation

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.

15. Others

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.

16. Windows

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.

17. Cygwin

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.

18. Development

    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.

19. Builds

20. automake/autoconf

    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

21. Editing

    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).

22. Ide – antje

    The author has no experience of using any IDE Integrated Development Environment) that includes code editing, building and debugging.

23. 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)

24. ddd

    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.

25. Testing

    There are a variety of ways of testing the njudge code, of which some are described below.

26. Test script environment

    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.

27. One-off

    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.

28. Releases

29. Procedures

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.

30. Files

    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.

31. Versioning

    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.

32. Cvs2log

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
5^th April 2004