AMule Project FAQ - User contributions [en]

Coding Style

2005-04-27T23:38:27Z

213.60.53.247: Adding wxStat ban and other minor stuff.

This article details the coding style that should be adopted when writing changes to the [[aMule]] codebase. Various useful information for [[aMule]] (new and old) [[aMule_devs|developers]] can also be found here.

== Formatting ==

=== Indenting ===

==== Use tabs ====

Always use tabs for indenting, do not use spaces. The size of each tab should be equal to 4 spaces.

==== Scopes ====

Indent inside new scopes, including classes, structs, functions, etc.

Examples:

if ( false ) {
...
} else {
...
}

class foo
{
foo() {
...
}
}

=== Whitespace ===

Place whitespace between brackets and keywords, and between operators and variables:

if (something == true);

rather than

if(something==true);

=== Brackets ===

Brackets are placed on the same line as the construct with the exception of non-inlined functions, structs and classes. Perfer the usage of brackets, even when optional, as in the case of ''if''/''while''/etc blocks.

=== Misc ===

* When using the trinary operator, place brackets to promote readability.
* Add a space after the ''//'' chars when writing comments.

== Documenting comments ==

Always remember to documment new functions and classes! Examples of documented classes can be found in can be found in ''CMD4Hash.h'', ''BarShader.*'', ''ServerListCtrl.*'' and others. More information on the usage and syntax of [http://www.stack.nl/~dimitri/doxygen doxygen] can be found in the [http://www.stack.nl/~dimitri/doxygen/manual.html doxygen documentation].

Use the following format, which is [http://www.stack.nl/~dimitri/doxygen doxygen] compatible.

=== Functions, classes, structs, etc ===

/**
* <Short description>
*
* [@param <Param_1 description>]
* [@param <Param_n description>]
* [@return <return value description>]
*
* [Long description]
* [@see <reference to other relevant function>]
*/

=== Variables, typedefs, constants, etc ===

//! <Description>

== Coding ==

=== Naming Style ===

Always try to use descriptive names, except when it adds nothing to the readability, such as iterator varibles and counters (''it'', ''i'', ''x'', ''y'', etc).

===== Functions =====

* Function names should follow the AllWordsAreUppercase convention
* Function arguments should follow the conventions for local varibles described below

===== Variables =====

* Names should follow the firstWordLowerCaseRestUpperCase convention
* Prefix global variables with ''g_''
* Prefix static variables with ''s_''
* Prefix member variables with ''m_''

===== Classes =====

* Prefix classnames with ''C''
* Names should follow the AllWordsAreUppercase convention

===== Constants =====

* Use ALLUPPERCASE names

* Whenever possible, prefer const variables to pre-compiler defines. We've already had problems with nameclashing caused by defines, so me might as well not increase the chances of it happening again. Actual constants also has the major advantage that we gain proper type-safety.

===== Filenames =====

* For classes, use the classname without the "C" prefix.

=== Const correctness ===

Remember to mark functions and arguments (pointers, references) as const where possible. This increases the ability for us to write safer code and is a good thing.

===== References =====

Always use references where passing large datatypes suchs as [http://www.wxwidgets.org/manuals/2.4.2/wx368.htm ''wxString''] and ''CMD4Hash'' and only use non-const references if we are going to change the passed variables.

=== Lists/etc ===

Only use raw arrays when absolutely nessesary, in ALL other cases use:
1) STL containers, or
2) wxWidgets containers

However, for consistency STL containers should always be used unless there is a major reason for doing otherwise. Using STL containers gives us the advantage of making it possible to use the many algorithms in the STL library and they are usually faster than the corresponding wxWidgets container.

=== Deleting ===

Deleting a NULL pointer is a valid operation, so checks against NULL only clutter the code needlesly.

=== Hacks ===

Always try to avoid odd hacks and in general try to avoid abnormal stuff, assignments in if constructs and the like for instance should be avoided when possible. Also try to avoid the usage of void pointers as they result in a almost total loss of type-safety.

=== Helper-functions ===

Helper functions which can have use across the app should be placed in ''otherfunctions.h''.

Whenever possible, prefer [[wxWidgets]] functions to system calls, as this reduces the dependencies on specific function-calls that may or may not be available on other platforms.

== IMPORTANT: What to avoid (The special 'I kill you' section!) ==

* Do NEVER NEVER use unicode2char and char2unicode functions at all. Same for unicode2UTF8 and UTF82unicode, and anything related to converting unicode wxStrings into char or wchar buffers. This is specially true with functions dealing with interface, where we should ALWAYS use wxStrings, and never use string conversion to construct that wxString.

:''The only places this is allowed is on printf() calls for debug. And if you REALLY need to use them in other scenario, like network communication or file handling use them VERY carefully. There are comments about the proper use at the beggining of StringFunctions.h. If you don't know if it's right or what to use, just ask, probably Kry is the best one to reply to that questions. Make someone review the code if you're not experienced and want to use that.''

* Do NEVER use wxString::c_str() or wxString::GetData() or similar functions. If you ever need to do such thing, it must be one of the special cases above where unicode2char can be used.

:''If you, for some reason, know that the string is ANSI (like the MD4 hashes stored on wxStrings), you can use c_str() there (NEVER GetData()!) to avoid the CPU usage of the conversion functions, but you MUST put a big warning about it above the function call.''

* Do NEVER use wxFile or wxFFile - use CFile instead. It has several bugfixes over wxFile, and it will work perfectly for handling UTF8 filenames on unicode aMule, such as anything non-ascii.

:''There should be no problem using wxFile and wxFFile for amule-related files, like server.met and others, that are never non-ansi, but the use of CFile is advisable to keep coherence over the system and easier replacement when a valid wxFile is released from wxWidgets devs.''

* Do NEVER use wxFind{First,Next}File. Use the CDirIterator class found in CFile.*. Reasons for this are the same as for wxFile and wxFFile: they don't handle unicode filenames properly.

:''No, there's not exception for this. Just never use it.''

* Do NEVER use wxStat or wxDirExists, use the static CFile::Stat() and CheckDirExists. Reasons are the usual ones: handling of unicode filenames.

:''No, there's not exception for this. Just never use it.''

* Avoid wxDateTime::Now().Format{Time, Date} as if it were Satan itself. Mainly, it asserts and breaks on several locale, mainly chinese and other asian languages. Use wxDateTime::Now().FormatISO{Time, Date}. People will have to live with english formated date and time strings.

:''No excuses for this either. It will have to go like this till wx devs fix it.''

* When you use a string to build a wxString, like "aMule", you MUST use wxT("aMule") if you want it not to be translated and _("aMule") if you want it to be translated. Failure to do so will result in aMule not being compilable in unicode mode, and the coder responsive will be killed and buried alive, not neccesarily in that order.

:''As a side note, debug messages should be ALWAYS in english, and messages meant to be for the user should be translated. This is so we can read debug info without translating it.''

* Do NEVER use CList/CTypedPtrList. This classes were a implementation of a MFC-compatible CList, and they are hand-made lists. they're known to be buggy and had to be fixed several times in the past. Instead, use stl containers or wxWidgets containers, as said on Lists/etc section. As a matter of fact, if you see a CList or CTypedPtrList on the code, clean it.

:''There are places in the code still using those classes, mainly the part about averages that Emilio wrote for the stats. The reason for this is mainly some special functions for recycle nodes as head/tail he added to the CList class. While this improved performance, it breaks the rules, and we should consider cleaning it. Other than that, there's no excuse to use CList classes.''

* Do NEVER use 'malloc' or 'free' unless absolutely neccesary. Use 'new' and 'delete'.

:''A example of a place where malloc can (and must) be used, is when dealing with C-libs, in all other cases it should be avoided!''

Probably more things I should remember, so I'll make this list bigger later.

== Usefull information ==

* [http://www.joelonsoftware.com/articles/Unicode.html Basic Introduction to Unicode].
* [http://www.sgi.com/tech/stl/table_of_contents.html An excellent reference to the STL implementation that GCC also uses].
* [http://www.acmqueue.com/modules.php?name=Content&pa=showpage&pid=271 How Not to Write FORTRAN in Any Language].
* [http://emuleplus.info/forum/index.php?showforum=23&hyperlink=/Developers/KB/Diagrams ED2K/eMule protocol flow-diagrams].

HowTo compile on Win32 with MinGW

2005-04-27T23:32:35Z

213.60.53.247: Actually cleaning for 2.0.0

<center><h2> originally by '''Madcat'''</h2></center>

This wiki page only supports the lastest CVS version of aMule.

== List of things you need to compile [[aMule]] ==

'''Note:''' Some of these require manually moving includes/libs into the right directories.

[http://www.microsoft.com/windows Windows] port of [http://gcc.gnu.org GNU C compiler] -> [http://prdownloads.sf.net/mingw/MinGW-3.1.0-1.exe?download Download]

Minimal [http://www.gnu.org GNU] shell for [http://www.microsoft.com/windows Windows] -> [http://prdownloads.sf.net/mingw/MSYS-1.0.10.exe?download Download]

Developer toolkit for [http://www.mingw.org/msys.shtml MSys] (for [http://www.gnu.org/software/cvs CVS] & co) -> [http://prdownloads.sf.net/mingw/msysDTK-1.0.1.exe?download Download]

[http://www.gnu.org/software/libiconv LibIConv] (required by [http://www.gnu.org/software/gettext gettext]) ->
[http://prdownloads.sf.net/mingw/libiconv-1.8.0-2003.02.01-1.exe?download Download]

[http://www.gnu.org/software/gettext GetText] (for [http://www.gnu.org/software/gettext po files], [http://www.gnu.org/software/automake/automake.html autogen.sh], etc) ->
[http://prdownloads.sf.net/mingw/gettext-0.11.5-2003.02.01-1.exe?download Download]

[http://www.zlib.org zlib] compression library ->
[http://www.zlib.net/zlib-1.2.2.tar.gz Download]

[http://www.microsoft.com/windows Windows] port of [[wxWidgets]] library ->
[http://prdownloads.sourceforge.net/wxwindows/wxMSW-2.6.0.zip Download]

== Common guidelines, issues, solutions ==

Generally, compile [[wxWidgets|wxMSW]] as static library. This avoids several linker issues, and provides you with static binary.

Link statically against ''[http://www.zlib.org zlib]'' and ''[[wxWidgets|wxMSW]]'' to avoid distributing extranous DLLs (and generally make life simpler).

You need to modify ''wx/setup.h'' file by hand (after installing [[wxWidgets|wx]]) and change ''[http://www.wxwindows.org/manuals/2.4.2/wx53.htm wxCheckListBox]'' to ''0'' (or, alternativly, configure [[wxWidgets|wx]] with ''--without-checklistbox''). Probably there's a better way around this, but I can't think of any right now.

== Compilation ==

The compilation itself it's actually just a matter of following the usual compilation way: ./configure && make

However, zlib detection might fail. If that's the case, you need to add ''--with-zlib=/local/'' to yout configure flags.

== Compiling with [http://www.parinya.ca/mingwstudio.html MinGW Studio] ==

NOTE: The compilation with MinGW Studio is deprecated right now and generally doesn't work ATM. Might work again in the future.

Since the 2004/07/17, you can find in [http://www.gnu.org/software/cvs CVS] the file ''amule.msp'' which is the project file relative to the [http://www.parinya.ca/mingwstudio.html MinGW Studio] IDE ([http://www.gnu.org/philosophy/free-sw.html Free] and under [http://www.gnu.org/copyleft/gpl.html GPL] at http://www.parinya.ca/ and shipped with precompiled [[wxWidgets|wxMSW]]).

Install [http://www.parinya.ca/mingwstudio.html MinGW Studio], add [http://www.zlib.org Zlib] and [http://curl.haxx.se Curl] compiled libs in The [http://www.parinya.ca/mingwstudio.html MinGW Studio] tree.

Then, open ''amule.msp'' with [http://www.parinya.ca/mingwstudio.html MinGW Studio], press '''F7''', and [[aMule]] "should" be compiled :)

Yes, I know, "compile" is not the same as "work" ... But it is a great begining

AMule problems

2005-04-10T18:52:46Z

213.60.53.247: Always

<center>
<h4>[[aMule_Project_FAQ:About|aMule]] common problems</h4>

<h2>by ''[[User:Jacobo221|Jacobo221]]''</h2>

'''English''' | [[AMule_problems-es|Español]] | [[AMule_problems-nl|Nederlands]]
</center>

== I get an "aMule already running: exiting" message on the terminal when starting aMule. Will I be able to start it in any way? ==
This message is very clear: aMule is already running. But this doesn't refer to the entire system, but that '''you''' (your user account) is running aMule already. 
You might, anyway, think there's no aMule running, since it crashed. But it sometimes happens that some processes aren't completly closed, instead they keep in a status known as ''zombie'' or ''defunct''. To know if this is your problem, run ''ps u | grep amule'' and if it shows any output, then there's some other aMule process running with your account. To kill it, either close it normally (if you can) or kill it with ''kill -9 <aMule-PID>'' or ''killall -9 amule'' or logoff and log in again (which, in most cases should also kill aMule processes, except if you executed aMule with ''nohup'' or something alike). 
If non of the above suits you, then you can run another aMule as another user (if you can log in with another account, of course). Read [[FAQ_aMule#Can_I_run_two_aMule_instances_at_the_same_time?|Can I run two aMule instances at the same time?]].

== aMule starts but is never shown, allthough it's working fine. What's going on? ==
This may happen if you set the incorrect type of SysTray in Preferences -> General -> "Systray Integration" and you set aMule to minimize to tray and you set aMule to start minimized. So you really took some time to brake it, didn't you? 
To be able to recover aMule's GUI, edit ''~/.eMule'' and search for ''StartupMinimized=1'' and once you find it, change that line to ''StartupMinimized=0''. The following script will do that for you: 
''sed s/StartupMinimized=1/StartupMinimized=0/ ~/.eMule > ~/.eMule.temp && mv -f ~/.eMule.temp ~/.eMule'' 
When you next start aMule set the correct SysTray integration in Preferences so that you can enable "Start minimized" without having aMule being hidden. 
If for some reason the above didn't work, try changing manually the Systray integration in your to the default "No systray integration" option. To do so, set the ''DesktopMode='' value in ''~/.eMule'' to ''4''. The following script will do that for you: 
''sed s/DesktopMode=[0-9]/DesktopMode=4/ ~/.eMule > ~/.eMule.temp && mv -f ~/.eMule.temp ~/.eMule'' 
'''NOTE:''' On [[aMule]] versions previous to 2.0.0rc4, you should set it to ''1'' instead of ''4'' since the Preferences storage changed a little.

== aMule starts but is never connecting/behaving very weird/crashing almost every few seconds/etc...? ==
aMule versions up to 2.0.0-rc3 shouldn't be linked against wxWidgets 2.5.x neither GTK2 although some Linux distributions tend to do so. Please make sure your aMule isn't the case. If unsure, paste you backtrace at [http://www.amule.org/amule/board.php?boardid=33 aMule's Backtraces forum] or join aMule's IRC channel #amule at irc.freenode.net

== Where are my downloaded files? ==
By default, aMule stores completed files in ''~/.aMule/Incoming'' but, since ''~/.aMule'' directory is a hidden directory, your file manager might not show it. Make sure you have enabled your file manager to show hidden files. 
By default, files being downloaded are placed in ''~/.aMule/Temp'', so again, this is a hidden directory and the file managed must be configured to show hidden files.

== Why is aMule taking so much CPU resources at start-up? ==
This happens because aMule is hashing new files found on the Shared Directories. If aMule is always taking a lot of CPU at startup and no new files have been added or modified in any way in the Shared Directories, then something is wrong. 
In aMule versions earlier than 2.0.0-rc3 this used to happen when having the Temp, Incoming or any Shared Directory in a FAT32 partition. Since aMule 2.0.0-rc3 this is not happening any more. 
Also, in aMule versions earlier than 2.0.0-rc4 filesystems with UTF-8 encoding (known to happen with SuSE 9.1) could present problems when some file or directory in the Shared Directories path contanied a special character. If this is your problem, there's a walkaround (thanks '''nachbarnebenan'''): after aMule has hashed all shared files (that is, when it stops taking a lot of your CPU's resources), close aMule and enconde ~/.aMule/known.met into UTF-8 encoding (you can do this with the application ''[http://www.gnu.org/directory/recode.html recode]'' by running the following command: ''recode u8 ~/.aMule/known.met''). This should be done whenever a files is added or modified in any Shared Directory. So, best option is to upgrade to latest aMule version. 
If non of the above helps you, then something went really wrong on ''known.met'' file, probably some external program or user broke it. Best option is to delete it, start aMule and let aMule rehash all files again.

== So now aMule starts, but why is it displaying this message: "No valid servers to connect in serverlist found"? ==
That's because you enabled the option "Auto connect to servers the static list only". So, disable it or add some server to the static list. 
To disable that option, go to Preferences -> Servers -> "Auto connect to servers the static list only" 
To add a server to the static list, go to the Servers window and right-click on the server you want to add to the static list. Then select "Add to static" and do this exact process wit all the servers you want to add to the static list.

== aMule connects to server, but it is always given Low-ID. Why? and, can I do something about it? ==
This can bue due to three reasons:
<ul><li>Some necessary port is not opened in your firewall. Read [[FAQ_eD2k-Kademlia#What_is_LowID_and_HighID?|this]] to get to know what to do and check [http://www.amule.org/testport.php here] if the ports are open.</li>
<li>The server is very busy or maybe badly configured, so it's giving you a [[Low-ID]]. There's nothing that can be done in this case other than reconnect or connect to some other server.</li>
<li>Some ISP forbid the use of p2p applications, such as aMule, by not allowing traffic through popular p2p ports. In these cases, configure aMule to use some other port. It would be even better if it was some popular port used for some other issue. It's been known that on some ISPs it worked with port TCP 25600.</li></ul>

== [[aMule]] was interrupted while completing a file and it is now never completing it (allthough it's 100% downloaded). How can I complete it? ==
This one is easy: Close [[aMule]]. Now go into the Temp directory (by default, ''~/.aMule/Temp'') and run the following command:

''touch ./*''

Finally, run [[aMule]] and let it complete the files.

== I just lost a download. Is there anyway I can recover it? ==
This is strange to happen, but it might, although in most cases it is the result of some non-aMule-related stuff going weird (or user's fault). 
Two things may have happened. Either *.part.met files were deleted, or *.part files were deleted. 
If *.part files have dissapeared, the only solution is to reastart the downloads from the beggining (if *.part.met files are still there, aMule will restart the downloads on next start). However this should '''never''' happen unless the user directly deleted them. 
If *.part.met files have dissapeared but *.part files are still in the Temp directory, then search if *.part.met.bak are also in the Temp directory. If they are, then just rename ''*.part.met.bak'' files to ''*.part.met'' just by running: 
''for file in *.part.met.bak; do mv -f "$file" "${file%.bak}; done'' 
Still, it could happen that, although you have the *.part files, neither *.part.met nor *.part.met.bak files exist any longer. In this case, you would have two ways ways to work out of this: 
Either, use [http://www.bigwillystyle42.com/index.php?dest=mfr MetFileRegenerator] (Java needed) to reconstruct the *.part.met files. 
Or, search again on aMule for the files you were downloading and rename their part number in the *.part.met files to the ones it used to have. For example, if you ware down loading ''aMule_1.2.6.tar.gz'' and that was being downloaded in Temp directory as ''008.part'', then that file used to have it's corresponding ''008.part.met'' file and, probably, it's ''008.part.met.bak'' file. But this two latter files have misteriously dissapeared. Then search again on aMule for ''aMule_1.2.6.tar.gz'' and start downloading it. Close aMule and you'll have this new download as, for example, ''011.part'' file in the Temp directory. Of course, this download will have it's ''011.part.met'' file. Well, rename ''011.part.met'' to ''008.part.met'' and then delete ''011.part'' (and ''011.part.met.bak'' if it existed). Now start aMule and you will have recovered the download from the point it was before the *.part.met files disapeared.

== Why does aMule suddendly become unresponsive to the mouse although it's not hanged? ==
It sometimes happens that you left a dialog window somewhere hidden in the desktop. aMule is waiting for that window to be closed, so it becomes unresponsive untill you click OK, Cancel, or whatever you have to click. 
So, make sure there's no aMule dialog left around in '''any workspace'''.

== Why are some files in my shared folders not shown in the Shared Folders window? ==
This could happen if you added this files after aMule has been started. Press the "Reload" button on Shared Folders window and it should find the new files and hash them (this may take some CPU time). 
However, on some releases it has happened that after restarting aMule, some files dissapear from the Shared Folders window alllthough they are in the shared folders. In such cases, the only way to have them back is to delete ''~/.aMule/known.met'' but, of course, on next aMule start, all shared files will have to be rehashed, and that'll take some time most probably.

== I always get a message about addresses.met when I start aMule. What's wrong? ==
This happens when you enable the option Preferences -> Servers -> "Auto-update serverlist at startup" and you have no serverlists' urls in ''addresses.dat''. You can either add some to ''addresses.dat'' by adding them at Preferences -> Servers -> List or just disable Preferences -> Servers -> "Auto-update serverlist at startup" if you don't really need it. 

== I sometimes get a message on the log about credits being lost. Should I be worried? ==
No, you don't need to be worried. Credits for a client are deleted after 150 days (more or less 5 months) without "seeing" that client. Also, bad clients might lose their credits too. So those messages are just for debug information, you souldn't worry about them.

== What should I do if I lose my ''cryptkey.dat'' file? ==
Losing that file will automatically make you loose all your credits with it, sorry. IF you will to start collecting credits again from this very moment, delete ''~/.aMule/preferences.dat'' too. If you don't, you'll be unable to collect credits on those [[client]]s which had sometime (before loosing the ''cryptkey.dat file) identified you.

== Why is Upload/Download limit always back to 0 after every restart? ==
This happened on aMule versions previous to 2.0.0-rc4 when you trying to set a Upload or Download limit value higher than the Upload or Download Capacity value. However, since version 2.0.0-rc4 this is fixed (read [[FAQ_aMule#What_is_the_real_point_on_setting_up_Line_Capacities_in_Preferences?_Shouldn't_aMule_only_care_for_the_Bandwidth_Limits?|What is the real point on setting up Line Capacities
in Preferences? Shouldn't aMule only care for the Bandwidth Limits?]] to understand why) and shouldn't happen anymore.

== Why is aMule ignoring the bandwith I set per slot? ==
The bandwidth set to each slot can be set in Preferences, but it will be ignored if the bandwidth set per slot doesn't allow at least three connections at the same time. 
So, the maximum speed allowed per slot is '''BandwidthLimit/3'''. 
Please do '''NOT''' confuse '''Bandwidth limit''' with '''Bandwith Capacity'''. Read [[FAQ_aMule#What is the real point on setting up Line Capacities in Preferences? Shouldn't aMule only care for the Bandwidth Limits?|What is the real point on setting up Line Capacities in Preferences? Shouldn't aMule only care for the Bandwidth Limits?]] since the meaning of the Bandwidth Capacity setting is not intuitive. 
Also, if [[aMule]] detects that, after having set all the slots for uploading, still some bandwidth is left before getting to the Bandwidth Limit, it will allow another slot and divide all the slot bandwidths to so use the same amount of bandwidth. 

Example: 
Bandwidth Limit: 7 KBps
Slot allocation: 2 KBps
When [[aMule]] sets the slots to some clients to upload to them, after giving out three slots, it will notice that tehre are no more 2KBps left, since the limit is 7 KBps, but there is still 1 KBps left in the bandwicth before reaching the Bandwidth Limit. So, It will allow another slot to upload to a client and, isntead of giving that last slot a 1 KBps bandwidth connection (and leave the rest with a 2 KBps bandwidth connetcion), it will give all four slots a 1.8 KBps bandwidth connection.

== Why can't I set aMule's download limit to more than X? ==
To keep the ED2K network alive, all ED2K clients have an upload/download limits ratio hardcoded which, depending on the upload limit set, is:

From 0KBps to 3KBps: 
DownloadLimit can't be more than UploadLimit*3 
From 4KBps to 9KBps: 
DownloadLimit can't be more than UploadLimit*4 
UploadLimit values over 9KBps: 
There's no DownloadLimit limitation.

Be carefull when setting 0KBps as Upload Limit . It might not mean what you think it is. Read [[AMule_problems#I_set_Upload_Limit_to_0KBps,_but_aMule_is_still_transfering._What_did_I_do_wrong?|I set Upload Limit to 0KBps, but aMule is still transfering. What did I do wrong?]] to make sure you understand it's meaning.

== I set Upload Limit to 0KBps, but aMule is still transfering. What did I do wrong? ==
Setting Upload limit to 0KBps will not stop transfers, instead, ''0'' value means '''unlimited''', so, it's right the opossite of you're trying to do. There's no way to stop aMule from uploading files, and that's the same on all ED2K clients (eMule, eDonkey, etc). Allowing people not to upload would bring the ED2K network to it's end. 
Even if you don't share any directory, the Temp directory will '''always''' be shared, so that files that you are downloading are shared with other clients.

== Why am I getting "Too many connections" messages on the terminal? ==
This happens when you set a very high value at Preferences -> Connections -> "Connection limits" -> "Max connections". If this value is as almost as big as the the amount of connections your system allows you to have, then aMule will fail to establish connections and display those messages (have in mind that other applications may also have some connections established). 
On Windows 9x/ME platforms there is a limit of 100 TCP connections so, although you might set aMule to establish more than 100 connections, it will be unable to do so. You can change Windows's TCP connections limit by editting the Windows Register ('''Start -> Run -> regedit.exe''') and setting (you'll most surely have to add the value since in most cases it doesn't exist): 
''HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\VxD\MSTCP\MaxConnections'' (which is a String type and it's value must be a 32-bit number).

== My progress bars have lost most of their 3D effect and look more ugly now. Can I turn its look back? ==
In most aMule versions setting the progress bar style to the most right on Preferences -> "GUI tweaks" is the way to have the progress bar have the best 3D effect. But in versions 2.0.0-rc4 to 2.0.0-rc6 the best 3D effect is given when the style bar is set to the middle. Setting it to the most right would give the progress bar a flat look while setting it to the most left will give it a dark look.

== All my downloads suddenly paused and I can't resume them. What's going on? ==

Check if there's any free space in the filesystem where the Temp directory is placed. If there is any at all, check if there's more free space than the minimum free space set at Preferences -> Files -> "Min disk space".

The minimum free space required for [[aMule]] is 9.28MB, since that's what [[aMule]] needs to be able to download a [[FAQ_ed2k#What_is_a_chunk?|part]] of a file.

== Why isn't [[aMule]]'s Preview working at all with MPlayer? ==
Since aMule 2.0.0-rc4 Preview command isn't being run in the same terminal as aMule. As a result, your Preview program may fail to start. This is the case of MPlayer. If you need a terminal to run your Preview player, use some command like ''xterm -e <preview-app>'' i.e.: 
''xterm -T "aMule preview" -iconic -e mplayer -idx''

== After exitting MPlayer on Preview, my aMule keeps locked? ==
Preview used to lock aMule on purpose until aMule reached version 2.0.0-rc4. As a result of this, people using MPlayer suffered from a bug on MPlayer which remains the main process in background when closing the main MPlayer window. The way to walk around this MPlayer bug on aMule versions previous to 2.0.0-rc4 is to exit MPlayer by pressing the '''Q''' key. Any way, it'd be better if you could possibly upgrade aMule to the latest versions.

== Why is ''Transfered'' a smaller number than ''Completed''? ==
It's a common mistake to think it should be bigger or, at least, equal. 
Please read [[FAQ_aMule#What_is_the_difference_between_Transfered_and_Completed_in_the_Tranfers_window?|What is the difference between Transfered and Completed in the Tranfers window?]] to know more about this.

== aMule always slows down my computer when it completes a download. Is this a normal behaviour? ==
Yes it is. When aMule completes a download it checks it has not been corrupted. Allthough this is already checked while downloading (by checking the chunk's hash values), once the file is completly downloaded aMule hashes all the chunks to check that the chunks which were previously downloaded weren't somehow corrupted by the user or an external application while the rest of the file was being downloaded.

== Is there any way to recursively select a whole directory and its contents? ==
Yes, there is. And it's simple:
*On [[aMule]] 2.0.0-rc4 or later, right-click on the icon of the directory you want to recusively select.
*On [[aMule]] 1.x and up to 2.0.0-rc3 (included), while clicking on the directory, hold the CTRL key. 
And that's it.

== I downloaded a file and it got corrupted somehow by my hard disk or some external application once completed. Can I avoid redownloading the whole of it? ==
If you still have the [[ed2k_link|ed2k:// link]], start the download again and when a whole chunk (9.28MB) has been downloaded (any chunk), close [[aMule]], rename the corrupted file to the filename the current download has (something like ''002.part''), touch the corrupted file (i.e.: ''touch ~/.aMule/Temp/002.part*'') and restart [[aMule]]. 
[[aMule]] will detect the completed chunks and the corrupted ones, and will only download the chunks which got corrupted.

LMule

2005-04-07T02:39:14Z

213.60.53.247: tp?

== [http://sourceforge.net/projects/lmule lMule] ==

[http://sourceforge.net/projects/lmule lMule] is a [http://www.kernel.org Linux] port of [[eMule]] client using [[wxWidgets]] (formerly known as [[wxWidgets|wxWindows]]) class library. 
The [http://sourceforge.net/projects/lmule lMule] project is no longer maintained or supported.

[http://sourceforge.net/projects/lmule lMule] was the original program, based on [[eMule]], from which [[xMule]] forked.

'''NOTE:''' [[aMule]] is a '''separate''' project and is '''not''' related to [http://sourceforge.net/projects/lmule lMule] in any way (apart from being originally a fork from it). However, it shares developers and friendship with the former lmule developers except current xMule mantainer.

FAQ aMule

2005-04-05T04:26:13Z

213.60.53.247: We should not tell people tricks that disrupt the network.

<center>
<h4>F.A.Q on [[aMule_Project_FAQ:About|aMule]]</h4>

<h2>by ''[[User:Jacobo221|Jacobo221]]''</h2>

'''English''' | [[FAQ_aMule-es|Español]] | [[FAQ_aMule-it|Italiano]] | [[FAQ_aMule-pt_BR|Português]] | [[FAQ_aMule-fr|Français]] | [[FAQ_aMule-de|Deutsche]] | [[FAQ_aMule-nl|Nederlands]]
</center>

== What is [[aMule_Project_FAQ:About|aMule]]? ==
'''''[[aMule]] is a multi-platform client for the [[FAQ_eD2k-Kademlia|ED2K file sharing network]] based on the windows client [[eMule]].''''' 
aMule started in August 2003 as a fork of [[xMule]], which is a fork of [[lMule]].

It currently supports Linux, FreeBSD, OpenBSD, Windows, MacOS X and X-Box on both 32 bits and 64 bits computers. It should be noted that the Windows port isn't ready for general usage yet.

[[aMule]] is intended to be as user-friendly and feature-plenty as [[eMule]] and to remain faithful to the look of [[eMule]], so users familiar with either [[aMule_Project_FAQ:About|aMule]] or [[eMule]] will be able switch between the two easily.

Since [[aMule_Project_FAQ:About|aMule]] is based upon the [[eMule]] codebase, new features in [[eMule]] tend to find their way to [[aMule]] soon after their inclusion in [[eMule]], so users of [[aMule_Project_FAQ:About|aMule]] can expect to ride the cutting-edge of [[FAQ_eD2k-Kademlia|ED2k]] clients.

The best part is, that it's developed by a great team which is even more user-friendly than [[aMule_Project_FAQ:About|aMule]] itself (if possible), so please join #amule on irc.freenode.net or visit the [http://www.amule.org/amule forums], if you have any suggestions, questions, problems, bugs, patches or what else you might think of.

If you are interested in joining the development team, please contact us either through the [http://www.amule.org/amule forums] or in the IRC channel.

== How do I view a client's credits? ==
You can see any client's credits (the credits you owe him) by right clicking on it's name and selecting Show Details. There is no specific value shown so you can either view the total amount of data that client has sent you or the Credits Modifier (which is called DL/UL Modifier). On that same dialog window, if that client is on your upload queue, you'll be able to view it's rate and score on you.

== What do those colors in the progress bar mean? ==
On the downloading transfers list: 
Red: Chunks in red are chunks with no sources on current session found. 
Blue: Chunks in blue are chunks with at least one available source. The more solid blue it is, the more sources available have been found. 
Yellow: Chunks in yellow are chunks which are being downloaded at this very moment. 
Black: Chunks in black are chunks which have been already downloaded and verified. 
Green: When a file is in green it means that it's been completely downloaded and successfully verified (so, it'll be in the Incoming folder). 
On the expanded transfers list (can be viewed by double-clicking a transfer): 
Black: Chunks which that client has and you don't have. 
White: Chunks which that client doesn't have. 
Green: Chunks which that client has and you have, too. 
Yellow:Chunks which that client is currently uploading to you. 
On the uploading transfers list: 
Black: That client has completed and verified that chunk. 
Grey: That client doesn't have that chunk. 
Have in mind that not all clients support telling other clients which parts they have already completed when uploading, so some clients might have no bar at all. 
On the shared files window: 
Red: When there's no source found to have that same chunk (apart from you, of course). 
Blue: The more solid the blue is, the more spread that chunk is. 
On the search windows: 
Black: Files in black are those which only a client has been found to have. 
Blue: Files in blue are those which two or more clients have been found to have. The more solid the blue is, the more clients have been found to have it. 
Red: Files in red are those which are already in the downloading queue. 
Green: Files in green are those which you are already sharing (you completely downloaded it).

== What are all these icons? ==
See section "Icons and what they signify" in the [[Getting_Started#Icons_and_What_They_Signify|Getting Started]] guide.

== What do those numbers in brackets in the sources column of the searches window mean? ==
Those are the clients who are known to have the complete file. Even if the number in brackets is 0, it doesn't mean that no one has the complete file, it juts means that no client has marked the shared file as "completed" (lots of clients don't do so). So, it's a way to have an idea of how many people have the complete file, but not the definitive way.

== What do all those numbers in the sources column in the transfers window mean? ==
The sources format is XX/YY + ZZ (WW) where 
XX stands for the amount of available sources (the amount of sources found you can download from). 
YY stands for the amount of found sources (the total amount of sources found) 
ZZ stands for the number of "Asked for another file" sources 
WW stands for the amount of sources from who you are currently downloading some chunk of that file.

== What do all those numbers in the priority column in the extended transfers window mean? ==
That's the queue position you have on that client for that specific file. Not all clients provide such information, so in some cases, nothing is displayed. 
The number in brackets is the amount of positions you have "moved" through that client's upload queue. '''Negative''' numbers stand for positions you have '''won''' in the queue since you were added while '''positive''' numbers mean positions you've '''lost''' since since you were added. Notice that when that number is negative, it is displayed blue, while when it's positive, it's displayed red.

== Why are there two transfer rates in the uploading transfer list? ==
When you are uploading some file to some client, the uploading transfer list will show the transfer rate (speed in KBps) in which you are uploading to that client. If, at the same time, that client is uploading to you some file (or files), then the transfer rate's format will change to XX/YY where XX stands for the speed at which you are uploading to that client and YY will stand for the speed at which that client is uploading to you. If you search in the downloading transfers list you'll find that client. 
This is useful if you are trying to get a rare file, since you can see which file that client is uploading to you and, if it's the rare file, you can set him a friend slot so that you upload to that client faster and gain more credits on that client (and consequently, download faster from the client).

== What is A4AF? ==
A4AF stands for ''Ask For Another File''. It is a way to optimize the resources on a specific download. 
When you try to download a file, aMule gets a list of clients who are sharing that file. Some of these clients might also share some other file which you are also trying to download and, so, you might have that client in two separate download queues. 
A4AF tries to avoid this situations. Why? Because you can't download two chunks at the same time from the same client. So, by setting A4AF in a specific download, you are telling aMule to search for any client in that file's download queue who is also in some other file's download queue and remove it from that other download queue. This way, you'll get more sources on that file. 
You can also set a specific download to apply A4AF in the opposite way, that is, to give sources to the other downloads. This should be done on downloads which are not to be downloaded with too much hurry or which should be downloaded after some other similar file has been downloaded (in a series of files, for example). 
This also can be seen as a way of establishing preferences in downloads.

When the request swapping is done, the Queue Rank will be maintained.

'''NOTE:''' A source with a QR lower than 50 in the download with the higher priority will never be swapped. This is done this way to ensure it starts downloading from it.

== What is the difference between Transfered and Completed in the Transfers window? ==
Transfered shows the amount of data you have received concerning that file. This data is downloaded in a compressed format. Once the data gets to your machine, aMule processes it and decompresses it. The total useful data that can be taken from that received data (that is, the parts of that data which are actually real parts of the file you are trying to download and not headers or such stuff) is the amount that can be viewed in the Completed column.

== What is the difference between pausing and stopping a transfer? ==
When a transfer is paused, all connections related to the paused transfer are broken with the other clients so that no data is transfered, but sources aren't dropped, so that when the transfer is resumed, [[aMule_Project_FAQ:About|aMule]] will try to connect to those sources it was transferring from.
Instead, when a transfer is stopped, all sources are dropped so, when it's resumed, [[aMule_Project_FAQ:About|aMule]] will start searching for clients who are sharing that file.

== What are all those files [[aMule_Project_FAQ:About|aMule]] creates the first time it is run? ==

Most them are the same as [[eMule|eMule]]'s.

Detailed information about each and a list of all of [[aMule]]'s files can be found [[aMule files|here]].

== Can I use [[eMule|eMule]]'s files and settings and vice-versa? ==
Most of them yes. The only ones you can't share between [[aMule_Project_FAQ:About|aMule]] and [[eMule]] are the program configuration (that is, preferences.ini in [[eMule]] and ''~/.eMule'' in [[aMule_Project_FAQ:About|aMule]]). All the [[FAQ_eD2k-Kademlia|ED2K network]] related files can be successfully shared between the two applications with no more effort than copying the files in ''~/.aMule'' to the [[eMule]]'s directory and vice-versa. But have in mind that some files in ''~/.aMule'' are [[aMule_Project_FAQ:About|aMule]] specific, such as ''amulesig.dat'' or ''aMule.tmpl'', so it's better to only move those files that are in both the [[aMule_Project_FAQ:About|aMule]] and the [[eMule]] directory.

Moving half downloaded files is easy: just move them from your [[eMule]] temp directory (by default ''C:\Program files\eMule\Temp'') into ''~/.aMule/Temp'' or whatever your temp directory is in your [[aMule]] configuration.

== What is all that stuff in amulesig.dat and onlinesig.dat? ==

I guess you already read what [[amulesig.dat_file|''amulesig.dat'']] and [[onlinesig.dat_file|''onlinesig.dat'']] are for [[FAQ_aMule#What_are_all_those_files_aMule_creates_the_first_time_it_is_run?|above]].

So, this files contain the current [[signature]] (the current [[aMule]] status, if enabled, of course).

Detailed information about each of thee files can be found in the [[amulesig.dat_file|''amulesig.dat'' article]] and the [[onlinesig.dat_file|''onlinesig.dat'' article]].

== I just installed [[aMule_Project_FAQ:About|aMule]] for the first time. How do I set it up? ==
Setting up aMule properly is just a matter of tastes and depends on many factors. If you just wish a quick startup configuration, then continue reading. 
Open [[aMule_Project_FAQ:About|aMule]] and click on the Preferences button. Set a nickname and the language in which you wish to have [[aMule_Project_FAQ:About|aMule]]. Then switch to the Connection tab and input your Line Capacities. Then input the Bandwidth Limits according to the maximum amount of bandwidth you want [[aMule_Project_FAQ:About|aMule]] to use. Then switch to the Directories tab and set a directory for both the temporary files (where files will be stored until they are completely downloaded) and the completed files. Finally, select the directories which you want to share. It is not recommended to share too much files. Read below "What are the best settings I can set to have a nice download rate". To select recursively all directories inside a certain directory read [[aMule_problems#Is there any way to recursively select a whole directory and its contents?|Is there any way to recursively select a whole directory and its contents?]].

== Will [[aMule_Project_FAQ:About|aMule]] handle my [[xMule]] and [[lMule]] files? What should I do? ==
[[aMule_Project_FAQ:About|aMule]] automatically handles both [[lMule]] and [[xMule]]'s configuration files, but in different ways: 
[[lMule]] has been discontinued for several years now, so [[aMule_Project_FAQ:About|aMule]] understands that you are replacing [[lMule]] with [[aMule_Project_FAQ:About|aMule]], so it renames ~/.lMule folder to ~/.aMule. If you used ~/.lMule/Temp and ~/.lMule/Incoming as your temporary and downloading directories respectively, you should change the paths in Preferences to ~/.aMule/Temp and ~/.aMule/Incoming respectively. 

If a ~/.xMule directory is found, it will be kept unchanged and [[aMule]] will just copy the configuration files found in it. That means that the files you were downloading will remain in the ~/.xMule directory if they were downloading there, but since [[aMule_Project_FAQ:About|aMule]] has handled [[xMule]]'s configuration files, it will use still use it. You can either live with that, or move directories ~/.xMule/Temp and ~/.xMule/Incoming into ~/.aMule and change directories in Preferences.

== How do I start my [[aMule_Project_FAQ:About|aMule]] experience? ==
Just click on the Connect button. You should have some servers listed on the Servers window, though. If you have no servers listed, then click on the little button below the Connect button in the Servers window before clicking the Connect button. After some time, [[aMule_Project_FAQ:About|aMule]] will be connected to some server (you'll know because in the lower right corner the "Not connected" message will disappear). When connected, switch to the Search window and search for the file you want and once you find the file you want, double-click on it. 
For general [[aMule_Project_FAQ:About|aMule]] usage, join [[aMule_Project_FAQ:About|aMule]] #amule in irc.freenode.net or ask in forums at [http://www.amule.org/amule http://www.amule.org/amule]

== What are the best settings I can set to have a nice download rate? ==
If you understood "Is there any limit on the [[FAQ_eD2k-Kademlia|ED2K]] network?" then you might have seen that, if your provider allows you, the best is to have the upload limit set to a minimum of 10 KBps. Also, if you understood "What is all that credits, rate and score stuff about?", you might also understand that the more you upload, the more you download, so take the upload limit up as much as you can. A good tip (thanks to kaouete) when you are trying to download some rare or "never completing" file, is, whenever you see someone uploading to you some chunk of that file, give that client a friend slot so that, if it tries to download something from you, it gets preference and you gain credits on that client.

== Is there a way to open a text file and load all the ed2k links from the file? ==
Yes, there is. Just place all the ed2k links you want to download in a text file, each ed2k link in a separate line. Name that file ''ED2KLinks'' then place it in ''~/.aMule'' and aMule will automatically detect it, add all those ed2k links to download and remove the file. 
You might want to read [[ED2KLinks_file|this]] to know more about this file.

== Can I manage [[aMule_Project_FAQ:About|aMule]] remotely through telnet in the same way I do with [[eDonkey2000|eDonkey]]? ==
Yes you can, but not exactly in the same way as you do with [[eDonkey2000|eDonkey]]. Just start a normal telnet (or ssh) session with the host computer (the one running [[aMule_Project_FAQ:About|aMule]]) and, once in, use amulecmd to take control over [[aMule_Project_FAQ:About|aMule]]. To start new downloads just use the [[ed2k_command|ed2k command]]. Remember [[aMuleCMD]] must be configured. 
Another aMule utility that might be of your interest is [[CAS]] (which's command is <code>cas</code>) which will show basic [[aMule_Project_FAQ:About|aMule]] statistics. 
Also, [[amuleweb|aMule WebServer]] might be what you are looking for if you can and don't mind using a web browser on the client computer. Have in mind that aMule WebBrowser must also be configured.

== Is there any way to start [[aMule_Project_FAQ:About|aMule]] with no graphical interface? ==

Yes. Since aMule 2.0.0-rc6, you can use aMule Daemon, which can be executed on the command line by typing ''amuled''. To control it, use either aMuleWeb, aMuleCMD or any other such application for remotely controlling aMule.

Anyway, up to aMule 2.0.0-rc6, [[aMule_Project_FAQ:About|aMule]] was a monolithic application. This means that core and GUI were whole inseparable block.

So, for those using an old aMule version or who refuse to use aMuled (aMule Daemon), there are still two walkarounds to run [[aMule_Project_FAQ:About|aMule]] on command line but they're not direct ways:
*Through ''[http://xfree.org/4.4.0/Xvfb.1.html Xvfb]''
*Through ''[http://www.realvnc.com VNC]''

'''Through ''[http://xfree.org/4.4.0/Xvfb.1.html Xvfb]:''' 
You should run <code>[http://xfree.org/4.4.0/Xvfb.1.html Xvfb]</code> and then run aMule in it. Afterwards you can take control over [[aMule_Project_FAQ:About|aMule]] using [[aMuleCMD]] and [[ed2k_command|ed2k]] in the same way as you would if you were accessing [[aMule_Project_FAQ:About|aMule]] remotely over telnet (see above).

Short example: 
Run [http://xfree.org/4.4.0/Xvfb.1.html Xvfb]: 
<code>Xvfb :1 -screen 0 640x480x16 &</code> 
Set display to use for amule: 
<code>export DISPLAY=:1</code> 
Then run [[aMule_Project_FAQ:About|aMule]]: 
<code>amule &</code> 
Note: After running <code>export DISPLAY=:1</code>, all graphical applications launched from that shell will be opened in [http://xfree.org/4.4.0/Xvfb.1.html Xvfb]'s display. To avoid this, you can run [[aMule_Project_FAQ:About|aMule]] with the following command, so that only [[aMule_Project_FAQ:About|aMule]] runs there: 
<code>DISPLAY=:1 amule &</code> 
'''INFO:''' See the [[Screen]] page to know more about the [[Screen]] command

'''Through ''[http://www.realvnc.com VNC]:''' 
It's also possible to use ''vncserver'' instead of [http://xfree.org/4.4.0/Xvfb.1.html Xvfb] to achieve something similar. Just install ''vncserver'' and execute ''vncserver :0 -geometry 1024x768'' followed by ''export DISPLAY=:0''. This will create a hidden [http://xfree.org X] server, accessible only remotely using a [http://www.realvnc.com VNC] client. Once the [http://xfree.org X] server is running, you will need a window manager to manage [[aMule]] window (well, it's not really needed, but it's useful if you want to be able to close [[aMule]] without simply killing it), I recommend [http://fluxbox.sourceforge.net FluxBox] due to its low CPU and memory requirements. Just start it with ''fluxbox &'' and then run [[aMule]] with ''amule &''. Now you can connect to the [http://www.realvnc.com VNC] server and see the [[aMule]] window.

Keep in mind that if [[aMule]] shows any dialog that requires user input (like the one showed the first time [[aMule]] is executed), it will get stuck there until someone connects to the [http://www.realvnc.com VNC] server and clicks ok in the dialog. Usually, this should only need to be done once (and this connection may be used to update the serverlist and set the preferences), from then on [[aMule]] will start without user interaction, showing only some informational messages at startup.

If you need help on this issue, search [[aMule_Project_FAQ:About|aMule]]'s [http://www.amule.org/amule forums] or join #amule [[IRC]] channel at irc.freenode.net and ask.

== Can I run two [[aMule_Project_FAQ:About|aMule]] instances at the same time? ==
Yes you can, although it is not recommended. [[aMule_Project_FAQ:About|aMule]] will only check if the concurrent user is running some [[aMule_Project_FAQ:About|aMule]] instance, so you can run as many [[aMule_Project_FAQ:About|aMule]] instances as user accounts you have access to. To do this, just run <code>xhost +</code> and then <code>su</code> as another user and run aMule from that shell. 
Be aware, since [[aMule_Project_FAQ:About|aMule]] can't check if a user is running [[aMule_Project_FAQ:About|aMule]] on another X display. So, if your account is already running some [[aMule_Project_FAQ:About|aMule]] instance in some other X display, do not run another [[aMule_Project_FAQ:About|aMule]] instance on another X display or you might end up with lost configuration settings and corrupt chunks.

== How can I get those nice [[aMule_Project_FAQ:About|aMule]] statistics some people post on the IRC channels? ==
You can either copy and paste [[CAS]]'s (C [[aMule_Project_FAQ:About|aMule]] Statistics) output (to execute [[CAS]], run <code>cas</code>) or, if you use xChat as your IRC client and have the Perl module installed, you could use [[XAS]] (xChat [[aMule_Project_FAQ:About|aMule]] Statistics).

== What is slot allocation? ==
Each upload is a slot, so, if you are uploading to five clients at the same time, you have five upload slots established. So, the amount of slot allocation is the bandwidth which each slot will be given. 
As an example, if your upload limit is 20KBps, you can set slot allocation to 2KBps which means 10 clients will be able to download from you at the same time, each of them at a maximum transfer rate of 2KBps. 
See section "Why is aMule ignoring the bandwidth I set per slot?" in [[AMule_problems|aMule common problem's FAQ]].

== What is a friend slot? ==
A friend slot is just a slot which is assigned to a client in the friends list. Only one friend can have a slot at the same time. Whenever that friend (who has the friend slot enabled) tries to download a file from you, it will be given highest priority in the uploads queue, since it has that slot always assigned. While that friend isn't downloading, that assigned slot will be given to the client with the highest priority in the upload queue, as expected.

== What is the real point on setting up Line Capacities in Preferences? Shouldn't [[aMule_Project_FAQ:About|aMule]] only care for the Bandwidth Limits? ==
aMule really only cares for the Bandwidth Limits. Line Capacities are only set for the Statics display. Let's see: Imagine you have a 100KBps connection, imagine you want to set the Limit at 40KBps because you have a web server which needs a minimum of 60KBps to serve all the petitions. Now imagine you download rare indonesian free songs. You most surely never download at more than 3KBps ever. So, you could set Line Capacities at 5KBps so that the graph at Statics has some meaning, since if you set it up as a 100KBps connection, the graph will show an horizontal line with no meaning at all.

== aMule is crashing quite often here. Can I set it to restart every time it crashes? ==
No, you can't. But you can have scripts to do so. Some of these scripts even work if aMule '''hangs''' but doesn't '''crash'''. 
The following scripts might suit your needs: 
[http://www.amule.org/amule/thread.php?threadid=1232 http://www.amule.org/amule/thread.php?threadid=1232] 
[http://www.amule.org/amule/thread.php?threadid=542 http://www.amule.org/amule/thread.php?threadid=542] 
[http://deepthought.ena.si/mulerunner http://deepthought.ena.si/mulerunner]

== Can I have aMule get data from the standard input to pass it to GDB or Valgrind? ==
Yes, you can. Up to aMule 2.0.0-rc3 this wasn't allowed, but as of version 2.0.0-rc4 you can with the parameter ''-i'' or ''--enable-stdin''. 
Anyway, people with aMule versions previous to 2.0.0-rc4 can use [http://www.amule.org/amule/thread.php?threadid=2474 phoenix's aMule stdin patch].

== How can I switch to aMule from eMule without losing my credits? ==
If you already read [[FAQ_aMule#What_are_all_those_files_aMule_creates_the_first_time_it_is_run?|about the meaning of aMule's files]], you might already know what you have to do: 
Get ''cryptkey.dat'', ''clients.met'' and ''preferences.dat'' files from eMule's config directory (usually, under Windows, something like ''C:\Program files\eMule\config'') and copy them into ''~/.aMule''. Now start aMule so it reads those files. You're done!

== What is all this [[rabbit]] story about? ==
Ah, yeah, this all began... ehm... well... I mean... follow the white [[rabbit]] ;-)

AMule files

2005-04-04T14:00:43Z

213.60.53.247: Too much rabbits

<center>'''English''' | [[AMule_files-nl|Nederlands]]</center>

Most [[aMule]]'s config files and data are the same as or is compatible with [[eMule|eMule]]'s.

Have in mind that you might not have all of them on your hard disk, since they are generated when needed.

Here is a list and the usage of each of them:
*'''~/.eMule:''' [[aMule]]'s old personal configuration file (version prior to [[aMule]] 2.0.0).
*'''[[addresses.dat_file|~/.aMule/addresses.dat]]:''' Contains a list of serverlist URLs to check (if enabled in Preferences) for new servers on startup.
*'''~/.aMule/amule.conf''': [[aMule]]'s personal configuration file (where most preferences are stored).
*'''[[amulesig.dat_file|~/.aMule/amulesig.dat]]:''' This is [[aMule_Project_FAQ:About|aMule]]'s [[signature|OnLineSignature]] file, which is the same as [[eMule|eMule]]'s [[signature|signature]] (see [[onlinesig.dat_file|''onlinesig.dat'']] below) but with extended information.
*'''~/.aMule/aMule.tmpl:''' This was the template file which [[amuleweb|aMule WebServer]] used in version prior to [[aMule]] 2.0.0.
*'''~/.aMule/aMule-online-sign.png:''' This file will only exist if [[CAS]] has been run sometime with the ''-o'' switch and ''~/.aMule/casrc'' was successfully configured. It is an image containing details on [[aMule_Project_FAQ:About|aMule]]'s status.
*'''[[casrc_file|~/.aMule/casrc]]:''' This file will only exist if [[CAS]] has been run sometime with the ''-o'' switch. It contains the settings for the [[CAS]] image creation.
*'''[[clients.met_file|~/.aMule/clients.met]]:''' Contains the public hashes of other known clients along with the credits it owes each of them.
*'''~/.aMule/clients.met.BAK:''' Backup of [[clients.met file]].
*'''[[cryptkey.dat_file|~/.aMule/cryptkey.dat]]:''' It contains the unique 384 bit private [http://www.rsasecurity.com/rsalabs/node.asp?id=2125 RSA] key of your [[client]].
*'''[[emfriends.met file|~/.aMule/emfriends.met]]:''' Contains your friends list configuration.
*'''[[ED2KLinks_file|~/.aMule/ED2KLinks]]:''' This file acts as an external interface to add downloads to [[aMule]].
*'''[[ipfilter.dat file|~/.aMule/ipfilter.dat]]:''' This file contains the [[IP]] ranges and access levels restrictions which will be passed to [[IPFilter]].
*'''[[known.met file|~/.aMule/known.met]]:''' This file stores the hashes and some details of your shared files like size, path, statics, etc.
*'''[[known2.met file|~/.aMule/known2.met]]:''' This file stores the verified [[AICH]] hashes of your shared files.
*'''[[lastversion_file|~/.aMule/lastversion]]:''' This is only for [[aMule_Project_FAQ:About|aMule]] to know if you changed your version or if it's the first time you run it.
*'''~/.aMule/logfile:''' This file contains the log of the last [[aMule_Project_FAQ:About|aMule]] execution.
*'''~/.aMule/muleconn:''' This file is a socket for [[aMule_Project_FAQ:About|aMule]] communications.
*'''[[onlinesig.dat_file|~/.aMule/onlinesig.dat]]:''' This is an [[eMule|eMule]] compatible [[signature|OnLineSignature]] file. It's used by other applications to know basic information on [[aMule_Project_FAQ:About|aMule]]'s stat. See also [[amulesig.dat_file|''amulesig.dat'']] above.
*'''[[preferences.dat_file|~/.aMule/preferences.dat]]:''' Contains the public key of your client, also known as user hash.
*'''~/.aMule/remote.conf:''' Configuration file for [[External Connections]].
*'''[[server.met file|~/.aMule/server.met]]:''' This is a list of all known servers and your preferences about them (priority, name, [[IP]], port and such).
*'''~/.aMule/server_auto.met:''' Here is where [[server.met file]]s are downloaded before merging them with [[aMule]]'s [[server.met file]].
*'''~/.aMule/server_met.old:''' Backup of [[server.met file]].
*'''~/.aMule/server.met.new:''' Temporal file while it is being written into disk. As soon as [[aMule]] is finished writting it, it is renamed to [[server.met file|server.met]].
*'''[[shareddir.dat_file|~/.aMule/shareddir.dat]]:''' Stores the paths to all shared directories.
*'''[[staticservers.dat_file|~/.aMule/staticservers.dat]]:''' Stores a list of [[static server]]s.

Other files in ''~/.aMule/'' are most surely backups of some of the above files.
Also, on the Temp directory (which is ''~/.aMule/Temp'' by default but can be set to any other on Preferences), [[aMule_Project_FAQ:About|aMule]] will create, for each download in queue, the following files:

*'''*.part:''' This file contains the downloaded parts (not chunks, since not completed chunks are also stored here) of the download. As [[aMule_Project_FAQ:About|aMule]] is able to download from more than one user at the same time, this file has the size of the complete file. The missing parts are filled with zeros.
*'''*.part.met:''' This file contains information on the downloaded parts of the download, the verified chunks, the hash values of the remaining chunks, etc.
*'''*.part.met.bak:''' This are backups of the ''*.part.met'' files. Every now and then aMule creates this backups since without the ''*.part.met'' file, a download has no meaning for aMule. If any ''*.part.met'' file "disappeared, you should rename the ''*.part.met.bak'' to ''*.part.met''.
*'''*.part.met.backup:''' This are temporal ''*.part.met'' while the data is being stored. As soon as [[aMule]] finishes writting the file, it is renamed to ''*.part.met''.
*'''*.part.met.seeds:''' This file only exists if you have enabled to store the [[IP]]s of sources of rare files in the preferences, so that [[aMule_Project_FAQ:About|aMule]] can try to connect to these sources again after a restart.

The directories in ''~/.aMule/'' have the following use:

*'''~/.aMule/Incoming/:''' By default, the directory where [[aMule_Project_FAQ:About|aMule]] stores the completed downloads (except Mac).
*'''~/Documents/aMule Downloads:''' By default, the directory where [[aMule_Project_FAQ:About|aMule]] stores the completed downloads (Mac only and version > 2.0.0).
*'''~/.aMule/Temp/:''' By default, the directory where [[aMule_Project_FAQ:About|aMule]] stores the non-completed downloads (temporary files).
*'''~/.aMule/webserver/:''' This directory contains the skins for [[aMuleWeb]].

AMule files

2005-04-04T13:59:42Z

213.60.53.247:

<center>'''English''' | [[AMule_files-nl|Nederlands]]</center>

Most [[aMule]]'s config files and data are the same as or is compatible with [[eMule|eMule]]'s.

Have in mind that you might not have all of them on your hard disk, since they are generated when needed.

Here is a list and the usage of each of them:
*'''~/.eMule:''' [[aMule]]'s old personal configuration file (version prior to [[aMule]] 2.0.0).
*'''[[addresses.dat_file|~/.aMule/addresses.dat]]:''' Contains a list of serverlist URLs to check (if enabled in Preferences) for new servers on startup.
*'''~/.aMule/amule.conf''': [[aMule]]'s personal configuration file (where most preferences are stored).
*'''[[amulesig.dat_file|~/.aMule/amulesig.dat]]:''' This is [[aMule_Project_FAQ:About|aMule]]'s [[signature|OnLineSignature]] file, which is the same as [[eMule|eMule]]'s [[signature|signature]] (see [[onlinesig.dat_file|''onlinesig.dat'']] below) but with extended information.
*'''~/.aMule/aMule.tmpl:''' This was the template file which [[amuleweb|aMule WebServer]] used in version prior to [[aMule]] 2.0.0.
*'''~/.aMule/aMule-online-sign.png:''' This file will only exist if [[CAS]] has been run sometime with the ''-o'' switch and ''~/.aMule/casrc'' was successfully configured. It is an image containing details on [[aMule_Project_FAQ:About|aMule]]'s status.
*'''[[casrc_file|~/.aMule/casrc]]:''' This file will only exist if [[CAS]] has been run sometime with the ''-o'' switch. It contains the settings for the [[CAS]] image creation.
*'''[[clients.met_file|~/.aMule/clients.met]]:''' Contains the public hashes of other known clients along with the credits it owes each of them.
*'''~/.aMule/clients.met.BAK:''' Backup of [[clients.met file]].
*'''[[cryptkey.dat_file|~/.aMule/cryptkey.dat]]:''' It contains the unique 384 bit private [http://www.rsasecurity.com/rsalabs/node.asp?id=2125 RSA] key of your [[client]].
*'''[[emfriends.met file|~/.aMule/emfriends.met]]:''' Contains your friends list configuration.
*'''[[ED2KLinks_file|~/.aMule/ED2KLinks]]:''' This file acts as an external interface to add downloads to [[aMule]].
*'''[[ipfilter.dat file|~/.aMule/ipfilter.dat]]:''' This file contains the [[IP]] ranges and access levels restrictions which will be passed to [[IPFilter]].
*'''[[known.met file|~/.aMule/known.met]]:''' This file stores the hashes and some details of your shared files like size, path, statics, etc.
*'''[[known2.met file|~/.aMule/known2.met]]:''' This file stores the verified [[AICH]] hashes of your shared files.
*'''[[lastversion_file|~/.aMule/lastversion]]:''' This is only for [[aMule_Project_FAQ:About|aMule]] to know if you changed your [[aMule_Project_FAQ:About|aMule]] version or if it's the first time you run [[aMule_Project_FAQ:About|aMule]].
*'''~/.aMule/logfile:''' This file contains the log of the last [[aMule_Project_FAQ:About|aMule]] execution.
*'''~/.aMule/muleconn:''' This file is a socket for [[aMule_Project_FAQ:About|aMule]] communications.
*'''[[onlinesig.dat_file|~/.aMule/onlinesig.dat]]:''' This is an [[eMule|eMule]] compatible [[signature|OnLineSignature]] file. It's used by other applications to know basic information on [[aMule_Project_FAQ:About|aMule]]'s stat. See also [[amulesig.dat_file|''amulesig.dat'']] above.
*'''[[preferences.dat_file|~/.aMule/preferences.dat]]:''' Contains the public key of your client, also known as user hash.
*'''~/.aMule/remote.conf:''' Configuration file for [[External Connections]].
*'''[[server.met file|~/.aMule/server.met]]:''' This is a list of all known servers and your preferences about them (priority, name, [[IP]], port and such).
*'''~/.aMule/server_auto.met:''' Here is where [[server.met file]]s are downloaded before merging them with [[aMule]]'s [[server.met file]].
*'''~/.aMule/server_met.old:''' Backup of [[server.met file]].
*'''~/.aMule/server.met.new:''' Temporal file while it is being written into disk. As soon as [[aMule]] is finished writting it, it is renamed to [[server.met file|server.met]].
*'''[[shareddir.dat_file|~/.aMule/shareddir.dat]]:''' Stores the paths to all shared directories.
*'''[[staticservers.dat_file|~/.aMule/staticservers.dat]]:''' Stores a list of [[static server]]s.

Other files in ''~/.aMule/'' are most surely backups of some of the above files.
Also, on the Temp directory (which is ''~/.aMule/Temp'' by default but can be set to any other on Preferences), [[aMule_Project_FAQ:About|aMule]] will create, for each download in queue, the following files:

*'''*.part:''' This file contains the downloaded parts (not chunks, since not completed chunks are also stored here) of the download. As [[aMule_Project_FAQ:About|aMule]] is able to download from more than one user at the same time, this file has the size of the complete file. The missing parts are filled with zeros.
*'''*.part.met:''' This file contains information on the downloaded parts of the download, the verified chunks, the hash values of the remaining chunks, etc.
*'''*.part.met.bak:''' This are backups of the ''*.part.met'' files. Every now and then aMule creates this backups since without the ''*.part.met'' file, a download has no meaning for aMule. If any ''*.part.met'' file "disappeared, you should rename the ''*.part.met.bak'' to ''*.part.met''.
*'''*.part.met.backup:''' This are temporal ''*.part.met'' while the data is being stored. As soon as [[aMule]] finishes writting the file, it is renamed to ''*.part.met''.
*'''*.part.met.seeds:''' This file only exists if you have enabled to store the [[IP]]s of sources of rare files in the preferences, so that [[aMule_Project_FAQ:About|aMule]] can try to connect to these sources again after a restart.

The directories in ''~/.aMule/'' have the following use:

*'''~/.aMule/Incoming/:''' By default, the directory where [[aMule_Project_FAQ:About|aMule]] stores the completed downloads (except Mac).
*'''~/Documents/aMule Downloads:''' By default, the directory where [[aMule_Project_FAQ:About|aMule]] stores the completed downloads (Just Mac and version > 2.0.0).
*'''~/.aMule/Temp/:''' By default, the directory where [[aMule_Project_FAQ:About|aMule]] stores the non-completed downloads (temporary files).
*'''~/.aMule/webserver/:''' This directory contains the skins for [[aMuleWeb]].

Coding Style

2005-03-31T03:35:28Z

213.60.53.247: woops

This article details the coding style that should be adopted when writing changes to the [[aMule]] codebase. Various useful information for [[aMule]] (new and old) [[aMule_devs|developers]] can also be found here.

== Formatting ==

=== Indenting ===

==== Use tabs ====

Always use tabs for indenting, do not use spaces. The size of each tab should be equal to 4 spaces.

==== Scopes ====

Indent inside new scopes, including classes, structs, functions, etc.

Examples:

if ( false ) {
...
} else {
...
}

class foo
{
foo() {
...
}
}

=== Whitespace ===

Place whitespace between brackets and keywords, and between operators and variables:

if (something == true);

rather than

if(something==true);

=== Brackets ===

Brackets are placed on the same line as the construct with the exception of non-inlined functions, structs and classes. Perfer the usage of brackets, even when optional, as in the case of ''if''/''while''/etc blocks.

=== Misc ===

* When using the trinary operator, place brackets to promote readability.
* Add a space after the ''//'' chars when writing comments.

== Documenting comments ==

Always remember to documment new functions and classes! Examples of documented classes can be found in can be found in ''CMD4Hash.h'', ''BarShader.*'', ''ServerListCtrl.*'' and others. More information on the usage and syntax of [http://www.stack.nl/~dimitri/doxygen doxygen] can be found in the [http://www.stack.nl/~dimitri/doxygen/manual.html doxygen documentation].

Use the following format, which is [http://www.stack.nl/~dimitri/doxygen doxygen] compatible.

=== Functions, classes, structs, etc ===

/**
* <Short description>
*
* [@param <Param_1 description>]
* [@param <Param_n description>]
* [@return <return value description>]
*
* [Long description]
* [@see <reference to other relevant function>]
*/

=== Variables, typedefs, constants, etc ===

//! <Description>

== Coding ==

=== Naming Style ===

Always try to use descriptive names, except when it adds nothing to the readability, such as iterator varibles and counters (''it'', ''i'', ''x'', ''y'', etc).

===== Functions =====

* Function names should follow the AllWordsAreUppercase convention
* Function arguments should follow the conventions for local varibles described below

===== Variables =====

* Names should follow the firstWordLowerCaseRestUpperCase convention
* Prefix global variables with ''g_''
* Prefix static variables with ''s_''
* Prefix member variables with ''m_''

===== Classes =====

* Prefix classnames with ''C''
* Names should follow the AllWordsAreUppercase convention

===== Constants =====

* Use ALLUPPERCASE names

* Whenever possible, prefer const variables to pre-compiler defines. We've already had problems with nameclashing caused by defines, so me might as well not increase the chances of it happening again. Actual constants also has the major advantage that we gain proper type-safety.

===== Filenames =====

* For classes, use the classname without the "C" prefix.

=== Const correctness ===

Remember to mark functions and arguments (pointers, references) as const where possible. This increases the ability for us to write safer code and is a good thing.

===== References =====

Always use references where passing large datatypes suchs as [http://www.wxwidgets.org/manuals/2.4.2/wx368.htm ''wxString''] and ''CMD4Hash'' and only use non-const references if we are going to change the passed variables.

=== Lists/etc ===

Only use raw arrays when absolutely nessesary, in ALL other cases use:
1) STL containers, or
2) wxWidgets containers

However, for consistency STL containers should always be used unless there is a major reason for doing otherwise. Using STL containers gives us the advantage of making it possible to use the many algorithms in the STL library and they are usually faster than the corresponding wxWidgets container.

=== Deleting ===

Deleting a NULL pointer is a valid operation, so checks against NULL only clutter the code needlesly.

=== Hacks ===

Always try to avoid odd hacks and in general try to avoid abnormal stuff, assignments in if constructs and the like for instance should be avoided when possible. Also try to avoid the usage of void pointers as they result in a almost total loss of type-safety.

=== Helper-functions ===

Helper functions which can have use across the app should be placed in ''otherfunctions.h''.

Whenever possible, prefer [[wxWidgets]] functions to system calls, as this reduces the dependencies on specific function-calls that may or may not be available on other platforms.

== IMPORTANT: What to avoid (The special 'I kill you' section!) ==

- Do NEVER NEVER use unicode2char and char2unicode functions at all. Same for unicode2UTF8 and UTF82unicode, and anything related to converting unicode wxStrings into char or wchar buffers. This is specially true with functions dealing with interface, where we should ALWAYS use wxStrings, and never use string conversion to construct that wxString.

''The only places this is allowed is on printf() calls for debug. And if you REALLY need to use them in other scenario, like network communication or file handling use them VERY carefully. There are comments about the proper use at the beggining of StringFunctions.h. If you don't know if it's right or what to use, just ask, probably Kry is the best one to reply to that questions. Make someone review the code if you're not experienced and want to use that.''

- Do NEVER use wxString::c_str() or wxString::GetData() or similar functions. If you ever need to do such thing, it must be on of the special cases above where unicode2char can be used.

''If you, for some reason, know that the string is ANSI (like the MD4 hashes stored on wxStrings), you can use c_str() there (NEVER GetData()!) to avoid the CPU usage of the conversion functions, but you MUST put a big warning about it above the function call.''

- Do NEVER use wxFile or wxFFile - use CFile instead. It has several bugfixes over wxFile, and it will work perfectly for handling UTF8 filenames on unicode aMule, such as anything non-ascii.

''There should be no problem using wxFile and wxFFile for amule-related files, like server.met and others, that are never non-ansi, but the use of CFile is advisable to keep coherence over the system and easier replacement when a valid wxFile is released from wxWidgets devs.''

- Do NEVER use wxFind{First,Next}File. Use the CDirIterator class found in CFile.*. Reasons for this are the same as for wxFile and wxFFile: they don't handle unicode filenames properly.

''No, there's not exception for this. Just never use it.''

- Avoid wxDateTime::Now().Format{Time, Date} as if it were Satan itself. Mainly, it asserts and breaks on several locale, mainly chinese and other asian languages. Use wxDateTime::Now().FormatISO{Time, Date}. People will have to live with english formated date and time strings.

''No excuses for this either. It will have to go like this till wx devs fix it.''

- When you use a string to build a wxString, like "aMule", you MUST use wxT("aMule") if you want it not to be translated and _("aMule") if you want it to be translated. Failure to do so will result in aMule not being compilable in unicode mode, and the coder responsive will be killed and buried alive, not neccesarily in that order.

''As a side note, debug messages should be ALWAYS in english, and messages meant to be for the user should be translated. This is so we can read debug info without translating it.''

- Do NEVER use CList/CTypedPtrList. This classes were a implementation of a MFC-compatible CList, and they are hand-made lists. they're known to be buggy and had to be fixed several times in the past. Instead, use stl containers or wxWidgets containers, as said on Lists/etc section. As a matter of fact, if you see a CList or CTypedPtrList on the code, clean it.

''There are places in the code still using those classes, mainly the part about averages that Emilio wrote for the stats. The reason for this is aminly some special functions for recycle nodes as head/tail he added to the CList class. While this improved performance, it breaks the rules, and we should consider cleaning it. Other than that, there's no excuse to use CList classes.''

Probably more things I should remember, so I'll make this list bigger later.

=== Malloc ===

Only use malloc when it is absolutely necessary, for instance when dealing with C-libs, in all other cases it should be avoided!

== Usefull information ==
* [http://www.joelonsoftware.com/articles/Unicode.html Basic Introduction to Unicode].
* [http://www.sgi.com/tech/stl/table_of_contents.html An excellent reference to the STL implementation that GCC also uses].
* [http://www.acmqueue.com/modules.php?name=Content&pa=showpage&pid=271 How Not to Write FORTRAN in Any Language].
* [http://emuleplus.info/forum/index.php?showforum=23&hyperlink=/Developers/KB/Diagrams ED2K/eMule protocol flow-diagrams].

Coding Style

2005-03-31T03:35:06Z

213.60.53.247:

This article details the coding style that should be adopted when writing changes to the [[aMule]] codebase. Various useful information for [[aMule]] (new and old) [[aMule_devs|developers]] can also be found here.

== Formatting ==

=== Indenting ===

==== Use tabs ====

Always use tabs for indenting, do not use spaces. The size of each tab should be equal to 4 spaces.

==== Scopes ====

Indent inside new scopes, including classes, structs, functions, etc.

Examples:

if ( false ) {
...
} else {
...
}

class foo
{
foo() {
...
}
}

=== Whitespace ===

Place whitespace between brackets and keywords, and between operators and variables:

if (something == true);

rather than

if(something==true);

=== Brackets ===

Brackets are placed on the same line as the construct with the exception of non-inlined functions, structs and classes. Perfer the usage of brackets, even when optional, as in the case of ''if''/''while''/etc blocks.

=== Misc ===

* When using the trinary operator, place brackets to promote readability.
* Add a space after the ''//'' chars when writing comments.

== Documenting comments ==

Always remember to documment new functions and classes! Examples of documented classes can be found in can be found in ''CMD4Hash.h'', ''BarShader.*'', ''ServerListCtrl.*'' and others. More information on the usage and syntax of [http://www.stack.nl/~dimitri/doxygen doxygen] can be found in the [http://www.stack.nl/~dimitri/doxygen/manual.html doxygen documentation].

Use the following format, which is [http://www.stack.nl/~dimitri/doxygen doxygen] compatible.

=== Functions, classes, structs, etc ===

/**
* <Short description>
*
* [@param <Param_1 description>]
* [@param <Param_n description>]
* [@return <return value description>]
*
* [Long description]
* [@see <reference to other relevant function>]
*/

=== Variables, typedefs, constants, etc ===

//! <Description>

== Coding ==

=== Naming Style ===

Always try to use descriptive names, except when it adds nothing to the readability, such as iterator varibles and counters (''it'', ''i'', ''x'', ''y'', etc).

===== Functions =====

* Function names should follow the AllWordsAreUppercase convention
* Function arguments should follow the conventions for local varibles described below

===== Variables =====

* Names should follow the firstWordLowerCaseRestUpperCase convention
* Prefix global variables with ''g_''
* Prefix static variables with ''s_''
* Prefix member variables with ''m_''

===== Classes =====

* Prefix classnames with ''C''
* Names should follow the AllWordsAreUppercase convention

===== Constants =====

* Use ALLUPPERCASE names

* Whenever possible, prefer const variables to pre-compiler defines. We've already had problems with nameclashing caused by defines, so me might as well not increase the chances of it happening again. Actual constants also has the major advantage that we gain proper type-safety.

===== Filenames =====

* For classes, use the classname without the "C" prefix.

=== Const correctness ===

Remember to mark functions and arguments (pointers, references) as const where possible. This increases the ability for us to write safer code and is a good thing.

===== References =====

Always use references where passing large datatypes suchs as [http://www.wxwidgets.org/manuals/2.4.2/wx368.htm ''wxString''] and ''CMD4Hash'' and only use non-const references if we are going to change the passed variables.

=== Lists/etc ===

Only use raw arrays when absolutely nessesary, in ALL other cases use:
1) STL containers, or
2) wxWidgets containers

However, for consistency STL containers should always be used unless there is a major reason for doing otherwise. Using STL containers gives us the advantage of making it possible to use the many algorithms in the STL library and they are usually faster than the corresponding wxWidgets container.

=== Deleting ===

Deleting a NULL pointer is a valid operation, so checks against NULL only clutter the code needlesly.

=== Hacks ===

Always try to avoid odd hacks and in general try to avoid abnormal stuff, assignments in if constructs and the like for instance should be avoided when possible. Also try to avoid the usage of void pointers as they result in a almost total loss of type-safety.

=== Helper-functions ===

Helper functions which can have use across the app should be placed in ''otherfunctions.h''.

Whenever possible, prefer [[wxWidgets]] functions to system calls, as this reduces the dependencies on specific function-calls that may or may not be available on other platforms.

== IMPORTANT: What to avoid (The special 'I kill you' section!) ==

- Do NEVER NEVER use unicode2char and char2unicode functions at all. Same for unicode2UTF8 and UTF82unicode, and anything related to converting unicode wxStrings into char or wchar buffers. This is specially true with functions dealing with interface, where we should ALWAYS use wxStrings, and never use string conversion to construct that wxString.

''The only places this is allowed is on printf() calls for debug. And if you REALLY need to use them in other scenario, like network communication or file handling use them VERY carefully. There are comments about the proper use at the beggining of StringFunctions.h. If you don't know if it's right or what to use, just ask, probably Kry is the best one to reply to that questions. Make someone review the code if you're not experienced and want to use that.''

- Do NEVER use wxString::c_str() or wxString::GetData() or similar functions. If you ever need to do such thing, it must be on of the special cases above where unicode2char can be used.

''If you, for some reason, know that the string is ANSI (like the MD4 hashes stored on wxStrings), you can use c_str() there (NEVER GetData()!) to avoid the CPU usage of the conversion functions, but you MUST put a big warning about it above the function call.''

- Do NEVER use wxFile or wxFFile - use CFile instead. It has several bugfixes over wxFile, and it will work perfectly for handling UTF8 filenames on unicode aMule, such as anything non-ascii.

''There should be no problem using wxFile and wxFFile for amule-related files, like server.met and others, that are never non-ansi, but the use of CFile is advisable to keep coherence over the system and easier replacement when a valid wxFile is released from wxWidgets devs.''

- Do NEVER use wxFind{First,Next}File. Use the CDirIterator class found in CFile.*. Reasons for this are the same as for wxFile and wxFFile: they don't handle unicode filenames properly.

''No, there's not exception for this. Just never use it.''

- Avoid wxDateTime::Now().Format{Time, Date} as if it were Satan itself. Mainly, it asserts and breaks on several locale, mainly chinese and other asian languages. Use wxDateTime::Now().FormatISO{Time, Date}. People will have to live with english formated date and time strings.

''No excuses for this either. It will have to go like this till wx devs fix it.''

- When you use a string to build a wxString, like "aMule", you MUST use wxT("aMule") if you want it not to be translated and _("aMule") if you want it to be translated. Failure to do so will result in aMule not being compilable in unicode mode, and the coder responsive will be killed and buried alive, not neccesarily in that order.

''As a side note, debug messages should be ALWAYS in english, and messages meant to be for the user should be translated. This is so we can read debug info without translating it.''

- Do NEVER use CList/CTypedPtrList. This classes were a implementation of a MFC-compatible CList, and they are hand-made lists. they're known to be buggy and had to be fixed several times in the past. Instead, use stl containers or wxWidgets containers, as said on Lists/etc section. As a matter of fact, if you see a CList or CTypedPtrList on the code, clean it.

- ''There are places in the code still using those classes, mainly the part about averages that Emilio wrote for the stats. The reason for this is aminly some special functions for recycle nodes as head/tail he added to the CList class. While this improved performance, it breaks the rules, and we should consider cleaning it. Other than that, there's no excuse to use CList classes.''

Probably more things I should remember, so I'll make this list bigger later.

=== Malloc ===

Only use malloc when it is absolutely necessary, for instance when dealing with C-libs, in all other cases it should be avoided!

== Usefull information ==
* [http://www.joelonsoftware.com/articles/Unicode.html Basic Introduction to Unicode].
* [http://www.sgi.com/tech/stl/table_of_contents.html An excellent reference to the STL implementation that GCC also uses].
* [http://www.acmqueue.com/modules.php?name=Content&pa=showpage&pid=271 How Not to Write FORTRAN in Any Language].
* [http://emuleplus.info/forum/index.php?showforum=23&hyperlink=/Developers/KB/Diagrams ED2K/eMule protocol flow-diagrams].

Coding Style

2005-03-31T03:33:21Z

213.60.53.247:

This article details the coding style that should be adopted when writing changes to the [[aMule]] codebase. Various useful information for [[aMule]] (new and old) [[aMule_devs|developers]] can also be found here.

== Formatting ==

=== Indenting ===

==== Use tabs ====

Always use tabs for indenting, do not use spaces. The size of each tab should be equal to 4 spaces.

==== Scopes ====

Indent inside new scopes, including classes, structs, functions, etc.

Examples:

if ( false ) {
...
} else {
...
}

class foo
{
foo() {
...
}
}

=== Whitespace ===

Place whitespace between brackets and keywords, and between operators and variables:

if (something == true);

rather than

if(something==true);

=== Brackets ===

Brackets are placed on the same line as the construct with the exception of non-inlined functions, structs and classes. Perfer the usage of brackets, even when optional, as in the case of ''if''/''while''/etc blocks.

=== Misc ===

* When using the trinary operator, place brackets to promote readability.
* Add a space after the ''//'' chars when writing comments.

== Documenting comments ==

Always remember to documment new functions and classes! Examples of documented classes can be found in can be found in ''CMD4Hash.h'', ''BarShader.*'', ''ServerListCtrl.*'' and others. More information on the usage and syntax of [http://www.stack.nl/~dimitri/doxygen doxygen] can be found in the [http://www.stack.nl/~dimitri/doxygen/manual.html doxygen documentation].

Use the following format, which is [http://www.stack.nl/~dimitri/doxygen doxygen] compatible.

=== Functions, classes, structs, etc ===

/**
* <Short description>
*
* [@param <Param_1 description>]
* [@param <Param_n description>]
* [@return <return value description>]
*
* [Long description]
* [@see <reference to other relevant function>]
*/

=== Variables, typedefs, constants, etc ===

//! <Description>

== Coding ==

=== Naming Style ===

Always try to use descriptive names, except when it adds nothing to the readability, such as iterator varibles and counters (''it'', ''i'', ''x'', ''y'', etc).

===== Functions =====

* Function names should follow the AllWordsAreUppercase convention
* Function arguments should follow the conventions for local varibles described below

===== Variables =====

* Names should follow the firstWordLowerCaseRestUpperCase convention
* Prefix global variables with ''g_''
* Prefix static variables with ''s_''
* Prefix member variables with ''m_''

===== Classes =====

* Prefix classnames with ''C''
* Names should follow the AllWordsAreUppercase convention

===== Constants =====

* Use ALLUPPERCASE names

* Whenever possible, prefer const variables to pre-compiler defines. We've already had problems with nameclashing caused by defines, so me might as well not increase the chances of it happening again. Actual constants also has the major advantage that we gain proper type-safety.

===== Filenames =====

* For classes, use the classname without the "C" prefix.

=== Const correctness ===

Remember to mark functions and arguments (pointers, references) as const where possible. This increases the ability for us to write safer code and is a good thing.

===== References =====

Always use references where passing large datatypes suchs as [http://www.wxwidgets.org/manuals/2.4.2/wx368.htm ''wxString''] and ''CMD4Hash'' and only use non-const references if we are going to change the passed variables.

=== Lists/etc ===

Only use raw arrays when absolutely nessesary, in ALL other cases use:
1) STL containers, or
2) wxWidgets containers

However, for consistency STL containers should always be used unless there is a major reason for doing otherwise. Using STL containers gives us the advantage of making it possible to use the many algorithms in the STL library and they are usually faster than the corresponding wxWidgets container.

=== Deleting ===

Deleting a NULL pointer is a valid operation, so checks against NULL only clutter the code needlesly.

=== Hacks ===

Always try to avoid odd hacks and in general try to avoid abnormal stuff, assignments in if constructs and the like for instance should be avoided when possible. Also try to avoid the usage of void pointers as they result in a almost total loss of type-safety.

=== Helper-functions ===

Helper functions which can have use across the app should be placed in ''otherfunctions.h''.

Whenever possible, prefer [[wxWidgets]] functions to system calls, as this reduces the dependencies on specific function-calls that may or may not be available on other platforms.

== IMPORTANT: What to avoid (The special 'I kill you' section!) ==

Do NEVER NEVER use unicode2char and char2unicode functions at all. Same for unicode2UTF8 and UTF82unicode, and anything related to converting unicode wxStrings into char or wchar buffers. This is specially true with functions dealing with interface, where we should ALWAYS use wxStrings, and never use string conversion to construct that wxString.

''The only places this is allowed is on printf() calls for debug. And if you REALLY need to use them in other scenario, like network communication or file handling use them VERY carefully. There are comments about the proper use at the beggining of StringFunctions.h. If you don't know if it's right or what to use, just ask, probably Kry is the best one to reply to that questions. Make someone review the code if you're not experienced and want to use that.''

Do NEVER use wxString::c_str() or wxString::GetData() or similar functions. If you ever need to do such thing, it must be on of the special cases above where unicode2char can be used.

''If you, for some reason, know that the string is ANSI (like the MD4 hashes stored on wxStrings), you can use c_str() there (NEVER GetData()!) to avoid the CPU usage of the conversion functions, but you MUST put a big warning about it above the function call.''

Do NEVER use wxFile or wxFFile - use CFile instead. It has several bugfixes over wxFile, and it will work perfectly for handling UTF8 filenames on unicode aMule, such as anything non-ascii.

''There should be no problem using wxFile and wxFFile for amule-related files, like server.met and others, that are never unicoded, but the use of CFile is advisable to keep coherence over the system and easier replacement when a valid wxFile is released from wxWidgets devs.''

Do NEVER use wxFind{First,Next}File. Use the CDirIterator class found in CFile.*. Reasons for this are the same as for wxFile and wxFFile: they don't handle unicode filenames properly.

''No, there's not exception for this. Just never use it.''

Avoid wxDateTime::Now().Format{Time, Date} as if it was Satan itself. Mainly, it asserts and breaks on several locale, mainly chinese and other asian languages. Use wxDateTime::Now().FormatISO{Time, Date}. People will have to live with english formated date and time strings.

''No excuses for this either. It will have to go like this till wx fixes it.''

When you use a string to build a wxString, like "aMule", you MUST use wxT("aMule") if you want it not to be translated and _("aMule") if you want it to be translated. Failure to do so will result in aMule not being compilable in unicode mode, and the coder responsive will be killed and buried alive, not neccesarily in that order.

''As a side note, debug messages should be ALWAYS in english, and messages meant to be for the user should be translated. This is so we can read debug info without translating it.''

Do NEVER use CList/CTypedPtrList. This classes were a implementation of a MFC-compatible CList, and they are hand-made lists. they're known to be buggy and had to be fixed several times in the past. Instead, use stl containers or wxWidgets containers, as said on Lists/etc section. As a matter of fact, if you see a CList or CTypedPtrList on the code, clean it.

''There are places in the code still using those classes, mainly the part about averages that Emilio wrote for the stats. The reason for this is aminly some special functions for recycle nodes as head/tail he added to the CList class. While this improved performance, it breaks the rules, and we should consider cleaning it. Other than that, there's no excuse to use CList classes.''

Probably more things I should remember, so I'll make this list bigger later.

=== Malloc ===

Only use malloc when it is absolutely necessary, for instance when dealing with C-libs, in all other cases it should be avoided!

== Usefull information ==
* [http://www.joelonsoftware.com/articles/Unicode.html Basic Introduction to Unicode].
* [http://www.sgi.com/tech/stl/table_of_contents.html An excellent reference to the STL implementation that GCC also uses].
* [http://www.acmqueue.com/modules.php?name=Content&pa=showpage&pid=271 How Not to Write FORTRAN in Any Language].
* [http://emuleplus.info/forum/index.php?showforum=23&hyperlink=/Developers/KB/Diagrams ED2K/eMule protocol flow-diagrams].