February 9th, 2009

Doxygen

So I’ve been playing around a little with Doxygen. If you don’t already know, Doxygen is tool for generating documentation from source code, similar to Javadoc in the Java world but a lot more powerful. It has support for generating documenation for a selection of programming languages including C, C++, Python, PHP, Java amoung others. Documentation is generated in HTML format by default but there are options for producing PDF’s, man pages, RTFs, CHMs and more.

The documentation is extracted from source files, using special comment blocks. Doxygen is able to filter out what is ment to be documentation and not just code comments. Since the documentation is in-lined with the source code there is a higher chance of the source and documentation staying consistent, if they are separated chances are that the documentation will become stale as the source code is changed but not reflected in the documentation.

I installed the Doxygen package on Windows and it comes with a handy GUI wizard for creating a configuration file and for running the Doxygen. There are lots of options available for working with Doxygen and the wizard makes it easier to get started, it also gives context sensitive information for each option so you know what each option is for.

When documenating your source code there are a few options for marking the documentation using special documentation blocks which are basically comment blocks. Doxygen supports the Javadoc style:

/**
 *  Documentation here
 */

As well as the Qt style:

/*!
  Documentation here
 */

Which style you choose is a matter of preference, personally I prefer the Javadoc style mainly because I’m used to it and have been using it with Java and PHP for a while so for this project I will continue using the Javadoc style to document my C++ source code.

By default Doxygen is able to generate simple diagrams that show inheritance for C++ classes but if you install a third-party package called Graphviz then Doxygen is able to take advantage of that and produce much more complicated and informative graphs and diagrams, including UML class diagrams.

Even on source code that has no documentation blocks, Doxygen is able to generate basic documentation of the code structure which is very useful when trying to understand a large source code distribution, couple this with the Graphviz generated diagrams it becomes very easy to visualize the code.

The diagram below was generated by Doxygen from Moge’s source code. It shows two of Moge’s classes GameEngine and Window, and shows the relationship between them, i.e. dependency, it also shows dependency on C++ Standard classes.

GameEngine class diagram

February 8th, 2009

Repository Backups

With the repository now housing the most important parts of the project, the documentation and the source code, it is very important that this resource be backed up.

In Subverion there are two types of backup methods:

  • Full - a full backup gathers all the information in the repository required to fully reconstruct the repository should a disaster occur.
  • Incremental - an incremental backup gathers the information that has changed in the repository since the previous backup.

The Moge repository uses the FSFS filesystem implementation and to keep things simple I will use a full backup. A full backup can be performed using the svnadmin subcommand hotcopy.

$ svnadmin hotcopy REPOS_PATH REPOS_BACKUP_PATH

This just takes a copy of the respository at REPOS_PATH and puts it at REPOS_BACKUP_PATH.

I created a little script to do the hotcopy and create a bzip2 archive with today’s date appended to the name. The script then emails the archive to a gmail account so I have a backup offsite. Archives remain in the backup folder for 30 days after which the script will remove them.

Next thing to do is to automate the backup to happen on a nightly basis, the Unix scheduler cron can be used for this very task. To tell cron to do jobs for you it requires a crontab which is a file that is read by cron and contains lines that define a job or task to be run with attributes defining when the job is to run. This file can be edited with the following command:

$ crontab -e

This will open the file in the default editor. There are 6 fields in a line to define a task, these are shown below:


# .---------------- minute (0 - 59)
# |  .------------- hour (0 - 23)
# |  |  .---------- day of month (1 - 31)
# |  |  |  .------- month (1 - 12) OR jan,feb,mar,apr ...
# |  |  |  |  .---- day of week (0 - 6) (Sunday=0 or 7)  OR sun,mon,tue,wed,thu,fri,sat
# |  |  |  |  |
  *  *  *  *  *  command

I want to run the backup daily at 3am, so I’d add a line as follows:
0 3 * * * /usr/local/bin/php /home/amorey/backup/mogeBackup.php

Once you save and exit the editor the crontab will be set.

February 4th, 2009

Version Control System

At a very basic level, a version control system, is like having a big undo feature for the entire project. Versions of a file can be reverted back to a previous version or even the entire project can be rolled back to a previous state. As changes are made and checked into the repository a log message is written to describe it, so later it is easy to generate a Changelog that shows the changes from release to release. While this project has only one developer, me, in general multiple developers would be involved in a project and having a VCS can help support collaboration while also providing accountability for each change made by each user.

I’ve used CVS and Subversion on other projects, so I have experience with both and know the benefits of both first hand. CVS is now an old version control system which lacks some features of newer version control systems. Knowing that there are many other systems available I’ve decided to use Subversion for my project as I know it has the features I need and I don’t have the time to invest into any other system.

Project Repository: http://svn.alanmorey.com/moge

February 3rd, 2009

Bug/Issue Tracking

In order to keep track of tasks, issues and bugs during the development of Moge, I’ve installed a bug tracking system called Mantis.

Mantis is a bug tracking system that uses MySQL and PHP.

As bugs or issues are discovered or created, an entry for it is added to the Bugs system. A list is assigned to each developer, which is me and provides a roadmap for the developer to follow in order to reach a milestone. As bugs/issues are then resolved their status is updated and the milestone becomes ever closer.

Tags: , ,
February 3rd, 2009

C++ Unit Testing

As part of my plan to handle testing I will incorporate some unit testing. In order to make the unit tests easier to develop and run I will use a Unit testing framework. Not having much experience with unit testing in general I will be looking for something fairly simple. I’d like to keep my dependencies on other languages down so I would like a framework that supports the writing of test cases and test suites in C++ and not a 3rd party language (scripting language).

I came across the following while searching around for C++ Unit Test frameworks:

  • CppUnit – it started out as port of jUnit, a testing framework for Java. While it seems to have a the features required of a unit testing framework, I feel that it may require a bit more work in setup. It has to be built and installed as a library.
  • MiniCppUnit – improves size wise on CppUnit coming in at ~500 lines and it doesn’t require a library installation
  • cutee – stands for C++ Unit Testing Easy Enviornment and reduces the amount of boiler plate code needed for creating unit tests
  • unit– – like cutee a simple and easy to use unit testing framework

After looking over these frameworks, I decided to go with the unit– framework it provides a very simple and easy API in the form of Macros that allow for quick creation of tests.

February 3rd, 2009

Project: MOGE

Moge stands for “Moreys Object-Oriented Game Engine”. Its to be developed as my final year project in “Software Development” for college.

  ____ ___   ____  ____  ____
 \  __' __`./  _ \/  _ \/ __ \
  \ \ \ \ \ \ \_\ \ \_\ \  __/
   \_\ \_\ \_\____/\____ \___\
                      __\ \
                      \____\

The aim of this project is to develop a non-commercial Game Engine, that focuses on the development of 2D games only. The Game Engine will provide the game developer with hardware acceleration for 2D graphics by using OpenGL graphics API, it will be built using Open-Source software libraries that are developed for cross-platform portability, thus allowing for the Game Engine to be used cross-platform. The Game Engine will expose an Object-Oriented API that follows sound Objected-Oriented design principles.