The Hacker's Guide to the MiNTLib
=================================

Please read this file if you intend to contribute code to the MiNTLib
project.

Patches
-------

Please always send patches, never complete files unless you have
really rewritten them from the scratch.  Otherwise you will make
it very difficult to integrate your code into the source tree.

If you create patches please proceed as follows.  Make a source
distribution of your current source tree.  This is easily done
if you cd into the toplevel directory and type "make dist".  Be
sure that you update the files SRCFILES, MISCFILES and BINFILES
if you add files, otherwise they will not get included in the
distribution (the same applies if you rename files).

Then unpack the original distribution that you got.  Rename the
directory to for example "mintlib-1.2.3.orig" or something.
Copy your newly created source distribution to the same directory
and then run:

diff -u -r --new-file --show-function-line=^[A-Za-z_] mintlib-1.2.3.orig mintlib-1.2.3

Make sure to specify the older directory first and the directory
that contains your patches second.  If your version of diff doesn't
support the options "--new-file" or --show-function-line" omit them.
If your diff can't create unified diffs (option -u), use "-C 2" 
instead.

Of course, if you only make minor modifications you can also diff
the individual files.  But making a source distribution ensures
that your patch is complete.

If your patches don't follow these rules, don't be supplied if they
will not be accepted.  I rather spend my time on coding then on 
figuring out what the heck you have modified.

Style
-----

The MiNTLib hasn't got any conventions for your code (unfortunately).
Feel free to code as you like it best but please be consequent.  Use
your style throughout the file.

If you change an existing file, please follow the style of the original
author or change it completely.  But be consistent.

Carriage Returns
----------------

Avoid them like the plague.  If your compiler needs carriage returns
please remove them before mailing patches (for example with the crlf
program, or with "tr -d '\r'").  If you can't remove the carriage
returns please mention that fact in the accompanying mail.

Tab stops
---------

Please don't use tab stops.  If you send your files to somebody else
who has other settings for the tab size your code will look really
ugly.  Hm, ok, if you use tab stabs, then set your tabsize to 8
because that's the standard for this library.

Namespace and Global Variables
------------------------------

Avoid global variables (unless documented) like the plague.  If you
absolutely need a global variable (or a global function) make sure
that it is prepended with a double underscore:

int __my_internal_function (int foobar);
int __my_internal_variable;

The MiNTLib namespace is currently very polluted; but don't follow
this example, do it better and remove namespace pollutions whereever
you encounter them.

Header Files
------------

Don't introduce non-standard header files.  At least put them into
subdirectories like "mint" or "sys".

Allow multiple inclusion for every header file you add.  If you
create a file "foobar.h" and "sys/foobar.h" put the contents between
preprocessor macros:

#ifndef _FOOBAR_H
# define _FOOBAR_H 1  /* Allow multiple inclusion.  */

...
#endif /* not _FOOBAR_H */

#ifndef _SYS_FOOBAZ_H
# define _SYS_FOOBAZ_H 1  /* Allow multiple inclusion.  */

...
#endif /* not _SYS_FOOBAZ_H */

Please use a single leading underscore for the macro.

Make sure that your header file will work with C++:

#ifdef __cplusplus
extern "C" {
#endif

...

#ifdef __cplusplus
}
#endif

Please _always_ include the header file <compiler.h>, /before/ 
you do the C++ stuff.

When prototyping functions you should either use no argument names
at all or begin them with a double underscore:

NOT:  __EXTERN foobar __PROTO ((int arg1));

BUT:  __EXTERN foobar __PROTO ((int __arg1));
OR:   __EXTERN foobar __PROTO ((int));

It is also a good idea to use descriptive names for arguments (not 
"__arg1", "__arg2", ...) and to place a short comment describing
the function before the prototype (convert argument names to
uppercase and omit the double underscore):

/* Return the `struct tm' representation
   of *TIMER in the local timezone.  */
__EXTERN struct tm *localtime __PROTO ((const time_t *__timer));

Comments
--------

Don't follow the rule "if it was hard to write it has to be hard
to read".  Make it easier for other people to fix bugs in your code
and write descriptive comments.

Describe as many variables that you use as possible.

Integer Sizes
-------------

This library is intended to compile and run with 32 and 16 bit integers.
Please keep that in mind.  If your code needs modifications for 16 bit
integers you can surround it by "#ifdef __MSHORT__".  It is also a good
idea to test your code both with 16 and 32 bit integers.

It is usually not necessary to take any special measures for -mbaserel
(unless you contribute assembler code).

To be continued ...
