Difference between revisions of "Development Information"

Latest revision as of 19:27, 18 June 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-10220). 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

Documentation should go inside the header files. Methods and members have to be documented at least with a brief description of their purpose. In the implementation files standard C++ comments can be used to point out what is happening in the lines of code. Obeying these guidlines ensures a consistent style of documentation and a useful autogenerated developers manual.

In simple cases (e.g. where a method has no parameters and the use can be described in one sentence) it is enought to use basic (brief) description comments:

class CKnownFile
{
    //! Returns the numbers of 9MB parts that are already hashed.
    uint16 GetPartCount() const { return m_iPartCount; }
...
    uint16 m_iPartCount;   //! Number of parts the file is split into.
}

In those cases where a detailed description is necessary (e.g. when a method has different parameters or does some complicated job) a special doxygen syntax should be used:

class CKnownFile
{
...
    /**
     * Updates the requency of uploading parts from with the data the client provides.
     *
     * @param client    The clients whoose uploading parts should be considered.
     * @param increment If true, the counts are incremented, otherwise they are decremented.
     * @return          THIS LINE IS ONLY NECESSARY IF THE METHOD HAS A NON-VOID RETURN VALUE
     *
     * This functions updates the frequency list of file-upparts, using the clients
     * upparts-status. This function should be called by clients every time they update their
     * upparts-status, or when they are added or removed from the file.
     */
    void UpdateUpPartsFrequency( CUpDownClient* client, bool increment );
...
}

If the method requires a detailed description but has no return value (void) then the @return marker can be omitted. In other cases of detailed comments the @return marker should describe the purpose of the value returned by the function. Visit the doxygen website to find out more about the doxygen syntax of comments. But please only use the ones shown above.

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

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.