Kernel hacker's guide to FreeMiNT
=================================

Everybody is welcome to improve the MiNT kernel and contribute
source code for bugfixes and enhancements.  Please help to keep
the source tree as clean as possible and avoid confusion by
adhering to the following rules:

 1. Before you apply major changes notify the current FreeMiNT
    coordinator of your plans.  (S)he will lock the corresponding
    parts of the source tree for you, thus making sure that no
    conflicting patches will be sent. See the file `README'
    in this directory for the e-mail address of the current 
    coordinator.

 2. FreeMiNT is a eUnuchs clone; please use eUnuchs newline 
    conventions for your source files (i.e. linefeed only and
    not carriage return/linefeed).

 3. The source tree currently requires 16-bit integers to build
    correctly.  However, future versions of MiNT should really
    compile with both 16- and 32-bit integers.  Please keep
    that goal in mind:
    
      - Avoid `int' for members of structures that are visible
        to the end user.  Use explicitely `short int' or 
        `long int' instead.
      - Avoid `int' for variables that are referenced by pointers
        visible to the end user.
     
 4. `If it was hard to write it doesn't have to be hard to read.'
    Harddisk space is cheap these days, do not worry about that
    when commenting your sources.  NEVER make changes to existing
    sources without giving the reason for your modification in
    a brief comment.

 5. Accompany your patches with a brief description suitable for
    insertion into one of the `CHANGES' or `NEWS' files.

 6. The idea of bootstrapping is fine but the additional effort
    is inacceptable.  The same applies to support for different
    development environments. Feel free to expect a minimum 
    configuration as follows:
   
      - The latest version of FreeMiNT in binary form.
      - Case-sensitive file system that supports long filenames
        (at least 32 characters).
      - GNU C compiler 2.7.x or higher, GNU assembler, archiver
        and linker.  Support for other binary tools in this
        distribution has informational character only and
        may be abandoned in future versions of FreeMiNT.
      - A POSIX compliant shell in u:\bin\sh (like the Bourne
        Again Shell `bash' by the Free Software Foundation).
      - GNU make 3.70 or higher.
      - Standard eUnuchs tools, utilities and commands available
        in path or as builtin shell commands:
     
          :, ., [, alias, awk, cat, cd, chmod, chgrp, chown, cmp, 
          compress (or gzip), cp, cut, date, diff, echo, ed, egrep 
          (resp. grep -E), env, ex, expr, false, fgrep (resp. grep -F), 
          find, grep, groups, head, hostname, id, install 
          (BSD-compliant), join, kill, lex (resp. flex), logname, ls, 
          mkdir, more, mv, nice, nm, nohup, od, patch, ps,  pwd, rm, rmdir, 
          rtfm, sed, sleep, sort, split, strip, su, tail, tar, tee, 
          test, time, touch, tr, true, umask, uname, uncompress 
          (or gunzip), uniq, uudecode, uuencode, vi, w, wait, wc, 
          which, who, whoami (or who am i), xargs, yacc (or bison), 
          zcat (or gunzip -c) ... (to be continued)
       
    You may expect these things to be present on other developers'
    machines and you may make references to these things when
    writing documentation.
   
    All tools are available for free download via anonymous ftp
    from various ftp servers all over the world.  Feel free to
    contact one of the MiNT people if you have difficulties
    to obtain them.

 7. Help to restructure the source tree.  Do not add anything to
    the current `monster source files', e.g. `dos.c', `proto.h'.
    Follow a modular approach instead, document all variables
    exported into the kernel in header files, do not pollute the
    kernel namespace but use static variables wherever possible.
    All global data should be properly commented including
    but not restricted to information about functionality,
    other dependencies, read/write access, and so on.

 8. When adding new system calls never rely on a fixed opcode!
    Avoid proprietary solutions, use standard calls wherever
    possible.  Try to provide a header file that may be inserted
    into the user's <include/sys> path with only minor changes.  You
    may embed kernel-specific stuff into conditional compilation
    by using the `__KERNEL__' macro which is guaranteed to be
    defined when building the MiNT kernel.

 9. Send diffs suitable for use with the `patch' command.  Read
    the documentation for the GNU diff utilities for information
    about how to do that.
 
10. Don't take the above rules to seriously.  Consider them as
    a guideline that makes the development of the FreeMiNT
    system more efficient and avoids frustration for your
    colleague developers.
