Difference between revisions of "Development Information"

Revision as of 20:02, 17 November 2009

Introduction

This page was created to help new developers understand how aMule is implemented. Basically the best way to learn about aMule is to take a look at the code itself. This however takes quite some time and is difficult to begin with when you are new to the project and don't know about the components and their interactions. Read on to get some help on getting started improving the application. We wish you success!

aMule comes with different utilities and is therefore not the only part of the aMule project. This wiki page however focuses on the aMule client application only!

Note: This site is work in progress. It was started by Marcell, because he found aMule was lacking documentation for developers.

The big picture

To get a first glimpse about aMule with a little insight into the boring details look at the aMule mind-map.

Note: This mind-map is based on the current knowledge of Marcell regarding the aMule client.

Translations

Here is a helpful documentation how the gettext catalogs and portable object files work: click me! It is a must read if you want to know the idea behind the gettext translation system and how developers and translators interact by using the appropriate conventions.

Updating translations

Updating translations is done by checking translated text marked as fuzzy or by adding missing translations for text string. Check the translation statistics page to find out whether you can help completing the language of your choice. If the status of the specific language is below 100% it means that we need your help. Here is what you have to do to help the aMule project:

1. Download the proper .po file for the language
2. Add .old to the file name. Example:
   • mv hu.po hu.po.old
3. Open the file with a gettext catalog editor (e.g: poedit)
4. Complete as much of the missing and fuzzy content as you can
5. Save your changes into a new .po file (e.g: hu.po.new)
6. Read the next section to find out how you can submit your changes

Creating the patch

This step ensures that the correct template (.pot file) is used so that the line numbers of the translated text strings are up to date and gives you the minimal difference between the old .po file (the one you downloaded) and your new .po file (the one with your changes applied). This lets the aMule staff apply your changes without the need to upload the whole new translation file itself.

1. Download the latest amule.pot file from the translation statistics page
2. Merge your translation and the template into a final .po file. Example:
   • msgmerge hu.po.new amule.pot > hu.po
3. Determine the changes in patch format. Example:
   • diff -u hu.po.old hu.po > hu.po.diff
   • Note:The first argument is the old file followed by the new one!

Submit the changes

Visit the aMule forum translations board and post a message in the proper topic of the language and attach the .diff file to it. This step requires you to register to the aMule forum. That's it. Soon a moderator or administrator will apply your changes and you can have good conscience having helped the aMule community.

Commit the changes

You have to be a developer for this, but devs need reminders too. :-)

1. copy the hu.po to the po directory
2. dos2unix hu.po
3. make hu.po-update
4. commit it

Documented code

The source code of aMule is documented inline with Doxygen compatible comments. This enables the generation of linked HTML documentation using Doxygen.
Here you can find the newest compressed version of the aMule Doxygen documentation (based on SVN-9866). Download and uncompress it, open the index.html file and start browsing.

Intention

The intention of this HTML documentation is to give you a fast and complete insight into all the classes and methods that are part of the aMule source code. It lets you browse any part that you are interested in and read about what is available and how it is implemented. This is especially useful when:

1. You are completely new to the aMule project
2. You want to implement something and don't know where the right place for it is
3. You would like to look at the source code in an interactive way without having to manually open dependent files and related sections

Note: The Doxygen documentation is not an official one and is provided by Marcell himself. Because of that it might be outdated and thus not reflect the most recent state of the code itself.

How to document the code

Brief description about how Doxygen documentation is done inside the code.