FAQ: Hacking MultiWeather

MultiWeather FAQ, version 0.1, Dec. 02, 2001 by psluis@caiw.nl [PJS]

This document contains helpful hints for anyone who is interested in adding to or modifying MultiWeather, or simply fixing bugs. This document concentrates on the types of hacks that I think people are most likely to want to implement. What you want to do may not be covered in this document, but you should read it anyway to get some idea of how you might have to proceed.

• 1. Code Style and Data Types
  • 1.1 Coding style
  • 1.2 Simple data types
  • 1.3 Naming conventions
• 2. A brief tour of MultiWeather's source code
• 3. Adding new source files
• 4. Debugging Support
• 5. Submitting your changes

MultiWeather's source code is Doxygen enabled. This means that it's comments have been tagged in such a manner, that doxygen can generate class/code documentation. In order to do this, you need to:

       cd mweather-x.x.x
       doxygen mweather.cfg

Doxygen generates Javadoc-style documentation which make browsing class hierarchies much easier. If you want to work with multiweather and be able to browse the source, I recommend doing this as a first step.

MultiWeather follows the GNU coding standard available on the GNU homepage. Use consecutive spaces to indent lines and avoid tab characters. Turn on tab expansion in your editor to avoid tab/space mixture hell. Keeping the code consistant makes the code base easier to read, but also allows code to be moved around between files without reformatting. A brief stylistic overview is given here:

gint a;
gint b;

gint a,
     b;

gint
function (gint i,
          gint j)

gint function (gint i, gint j)

if (foo == NULL)
  {
    printf ("Hello\n");
  }
else if (bar == NULL)
  {
    printf ("World\n");
  }
else
  {
    printf ("!\n");
  }

if (!foo)
  printf ("Hello\n");
else
{
  if (!bar)
    printf ("World\n");
  else
    printf ("!\n"); 
}

(x + y) / 2.0

(x+y)/2

func () + func2 (x, y)

func()+func2(x,y)

array[i]

array [i], array[ i ]

If your changes are minor, such as fixing a bug, you should strive to work within the existing set of source code files. Unless the "bug" is a fundemantal design flaw or something equally serious, you shouldn't have to add or remove any source files. If you are considering a bug fix of such significant scope, you should probably contact PJS before proceeding.

If you've gotten this far and you are still convinced that you need to create some new source files, for reasons of code sharing, keeping functionality isolated in well defined modules, or whatever, then that's ok. In this case, you should probably contact PJS before proceeding, to make sure he hasn't already taken the filenames you propose to use, and to make sure that your reasons for adding new source files are sound. Keep in mind that PJS is more likely to accept changes that do not involve radical changes to the code base. The type of modification that most commonly involves adding new source files are ones that involve creating new dialog boxes for the user to interact with. This is a consequence of the general method of writing code that uses the gdk/GTK+ toolkits. Of course, new features almost always require some type of user interaction, so if you're adding new functionality you can almost bet on having to create a dialog box or two and add some source files for that.

MultiWeather uses the autoconf system to generate its Makefiles, so adding new source files is easy. Just put them in MultiWeather's src/ directory, add the filename to src/Makefile.am and then then re-run the configure script in your MultiWeather directory in order to generate new Makefiles that will recognize your new source files.

Once you have implemented all your modifications, confirmed them against the most recent version of MultiWeather, and debugged your work, then you should submit your new code to the MultiWeather Mailing List. That way other users can see and comment on your code, and PJS can, if he finds it worthy, add your code to the main MultiWeather source distribution. Here's one way to do that, using tcsh. There are many other ways, of course:

1. Make a gzipped tar file (.tgz) containing the diffs between any files you changed and the original versions of those files. Note that at this point it will be very convenient if you've kept copies of the original files, in some other filename. Whenever I modify a MultiWeather source file, I always copy it first to a name of the form "original_name.orig" for safekeeping, as in "mainwindow.c.orig". Let me say again that it is highly desirable that your diffs be made against the most recent source code release.
   

   ~/mweather-0.0.1/src/> foreach name (*.orig)
   foreach? set oldname=`basename $name .orig`
   foreach? diff $oldname $name > $oldname.diff
   foreach? end
   ~/mweather-0.0.1/src/> cd ..
   ~/mweather-0.0.1/> tar -czf myusername.0.0.1.tgz src/*.diff
   

2. Uuencode your .tgz file:
   

   ~/mweather-0.0.1/> uuencode myusername.0.0.1.tgz myusername.0.0.1.tgz > myusername.0.0.1.uu
   

3. Post your changes to the multiweather mailing list:
   

   ~/mweather-0.0.1/> mail -s 'my specific multiweather mods against v0.x.x' < myusername.0.0.1.tgz
   

Note that your tar file should be named with your username and the version of multiweather to which your changes apply, as in the above example. Further, if you have made substantial changes to any of the multiweather source files such that a diff would be impractical, then you may choose to simply include that whole file in your .tgz file. However, please use diffs wherever possible.