DevelopersTips

Contents 1 Ocaml 2 Learning functional programming 3 Learning Objective Caml 4 Contributions in C to mldonkey 5 Learning the GUI-Protocol 6 Guidelines for the release of a new version 7 Developing new features

Ocaml

MLdonkey is primarily developed in the ObjectiveCaml language.

• the Ocaml standard distribution includes the Camlp4 preprocessor, a complete standard library, a backstep debugger (one can go back in time !), a toplevel interpreter, a bytecode compiler and a native code compiler, plus several other development tools. Distributions exist for a large number of platforms.

• For documentation, the ocamlbrowser class browser and the ocamldoc javadoc-like tool are included in the standard distrib. Ocamlp4 can also be used as a code beautifier.

• cameleon is a Linux IDE that integrates most Ocaml dev tools. There is also a GUI for the debugger. There is also a DLL for the Microsoft Visual dev environment.

• if you're another emacs addict, the good tuareg mode is strongly recommended.
• Vim also has an Ocaml mode.
• Nedit also has an Ocaml mode.
• OcaIde is a very nice, user-friendly Ocaml plugin for Eclipse, a good startpoint for ocaml's newbies
• otags is a handy TAGS generator for ocaml sources.

• there's an amazing amount of ObjectiveCaml resources out there. ocaml.org is a good starting point.

Learning functional programming

• The wikipedia functional programming entry
• The Functional programming FAQ
• A list of tutorials
• Another tutorial

Learning Objective Caml

• Objective CAML Tutorial
• Tutorials

Contributions in C to mldonkey

Extracts from the MLD users list by MLDonkey himself :

mldonkey really suffers from its lack of developers. Since the main problem is that a lot of people don't know ocaml, I think there is still a way for them to contribute to mldonkey development: simply by writting C code to perform the actions they want. The only problem will be that:

• the C code has no access to mldonkey internals
  
• the C code cannot communicate (open sockets, read/write, etc)

However, a lot of things can be performed this way: for example, a parser for jigle pages or sharereactor html pages could be done like that:

a structure (C struct) containing the search would be passed to a first C function to generate the url to be queried:

struct search {
  search_keywords: char*;
  search_num : int;
};

void search_jiggle(struct search *s){
   char *url;
   ...

   ... save somewhere the url with the search_num associated ...
   mldonkey_download_url(url, \"jiggle_callback\");
   free(url);
}

We suppose here that mldonkey provides a function 'mldonkey_download_url' to declare urls to be downloaded in the future.

void jiggle_callback(char url, char page)
{
  ... the page is the one that would be returned by wget for example ...

  ... some code to find the search_num associated with the url ...


  while(1){
    ... parsing the page ...
    mldonkey_add_search_result(search_num, result);
    free_result(result)
  }
}

where we suppose that mldonkey provides a function 'mldonkey_add_search_result' to add results to a search. Of course, the jiggle_callback function could also recall 'mldonkey_download_url' to recursively fetch other urls (but these urls will not be downloaded immediatly !)

Such 'mldonkey_' functions could easily be written by ocaml devs (on C devs requests), while the C code would be written by C devs. The stubs to call the C functions from the ocaml code would also be written by ocaml devs. So, no need of ocaml knowledge to do that. The only requirements are:

• The C functions must be called with well-defined arguments (strings, int, simple structs)
• The 'mldonkey_' functions cannot do anything except storing the results, until the C function code is completely executed (in this example, the URL will be downloaded after 'search_jiggle' has been executed, and the results will really be added when 'jiggle_callback' has completely been executed).
• The C code is responsible for desallocating any data allocated by itself.

Sidenote : !! Adding C code is NOT the best way to contribute !!

Learning the GUI-Protocol

The GUI-Protocol is the way an external graphical interface communicate with MLDonkey using sockets and TCP/IP. You can program your own GUI in every language you like and use the GuiProtocol to control your MLDonkey. Also may want to have a look at the others user interfaces.

Guidelines for the release of a new version

As example version 2.7.3 is used. --Spiralvoice 15:53, 12 April 2006 (PDT)

• check that the code compiles on several platforms
• update config/configure.in, lines 23-25 and distrib/Changelog to reflect new version number, like this
• cvs commit -m "release-2-7-3"
• cvs tag release-2-7-3
• create sourcecode tarball

• this script is used to return the version number of used sourcecode used in other scripts

#!/bin/sh
case $# in
    1)
        cdir=$1
        ;;
    *)
        cdir=`pwd`/mldonkey
        ;;
esac
major_version=`grep -m 1 MAJOR_VERSION= $cdir/config/configure.in | cut -c 15-17`
minor_version=`grep -m 1 MINOR_VERSION= $cdir/config/configure.in | cut -c 15-17`
sub_version=`grep -m 1 SUB_VERSION= $cdir/config/configure.in | cut -c 13-14`
echo $major_version.$minor_version.$sub_version

• Now the tarball creation script

#!/bin/sh
rm -rf ./mldonkey-cvs-create
mkdir mldonkey-cvs-create
cd mldonkey-cvs-create
cvs -z3 -d:pserver:anonymous@cvs.savannah.nongnu.org:/sources/mldonkey co -P mldonkey
version=`../mld_version.sh ./mldonkey`
mv ./mldonkey ./mldonkey-$version
cd ./mldonkey-$version/config
if [ -f ./configure ] ; then
    rm ./configure
fi
if [ -f ../Makefile ] ; then
    rm ../Makefile
fi
autoconf
m4 Makefile.in > ../Makefile
rm -rf ./autom4te.cache
cd ../..
tar --exclude=CVS --exclude=.cvsignore -cf ./mldonkey-$version.tar ./mldonkey-$version
bzip2 -zv9 mldonkey-$version.tar

• Gentoo ~x86 is used with current autoconf/m4 to create the configure script.

• unpack the tarball and test compile
• upload the sourcecode to Sourceforge
• post release notes on Savannah, Sourceforge, Freshmeat, english and german forum.
• build binaries

• the Linux x86, glibc-2.3.2 version is built on current Debian Sarge from a freshly downloaded sourcecode tarball

./configure --enable-checks --host=i386-pc-linux-gnu
make release.mlnet.static
make release.utils.static

• so it can be used on older platforms as well.
• Using Debian has the advantage that, in contrast to highly optimized Gentoo, it produces i386 binaries.
• upload mldonkey-2.7.3.static.i386-Linux_glibc-2.3.2.tar.bz2 to Sourceforge

• Send Email Release Notice in Sourceforge file release admin panel

Developing new features

eMule >4GB support
eMule protocol obfuscation
eMule AICH support