Difference between revisions of "Development Information"

Revision as of 21:37, 1 February 2010

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

Note: For updating man pages and submitting the changes please read the wiki part related to Translating the Documentation.

Submit the changes

Visit the aMule forum translations board and post a message in the proper topic of the language and attach the .po file to it. This step requires you to register to the aMule forum. That's it. Soon a developer 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.

Subversion

Subversion (or in its short form: SVN) is the source versioning tool used to maintain the code of aMule. A very helpful e-book about its functionality can be found here. This section sums up to most common commands you will make use of if you have access to the aMule SVN repository.

• svn co [svn-url] [target-dir]

Initial checkout of the source tree

• svn update

Update your local working copy to the latest shared revision

• svn update -r [revision-num]

Update your local copy to the revision specified by [revision-num]

• svn commit -m [brief-msg]

Write the changes you made to the shared repository

• svn revert [brief-msg]

Undo all the changes you made to your local working copy

• svn status

Show a status of changed files in your local copy

• svn diff

Show the exact differences made to files in your local copy

• svn log

Show a list of messages for each available revision number

Durring the commitment of changes you have to keep an eye out for resolving conflicts regarding changes made to the same file by different users. Before applying your changes to the shared repository, always update the local working copy first.