Read Me

What is Manarchive:
===================

Manarchive (Mercury Anarchy Archive) is a multi-purpose collection of libraries
in the Mercury programming language. The libraries can be used separately.
Manarchive provides a common development and testing platform.


Manarchive Objective:
=====================

Given the harsh committing policy of the Mercury team I thought of introducing
some anarchy ;-) and started Mercury Anarchive. The name can be shortened to
Manarchive or Mana (pronounced either like mana or manna [mannah], depending on
your religious background).

Manarchive will be a repository for generally useful routines, like c?an's are
for Perl, TeX, R-Project and others. I am not too ambitious at this point.


Manarchive Usage Aims:
======================

1. Using Manarchive should be as simple as possible, something like:

    svn checkout
    make  # to compile all the parts that have prerequisities satisfied
          # (some of the packages might depend on some libraries
          # installed; only users wanting such packages should be forced
          # to satisfy the prerequisities)
    mmc --make \
        `manarchive-config --print-mmc-flags --package X --package Y` \
        myproject
          # to link against packages X and Y (if they were successfully made)

    Manarchive must be usable both with libraries 'installed' (all grades
    generated) and with libraries 'non-installed' (just your favourite grade,
    for quick debugging of the library)

2. Contributing must be as simple as possible, something like:

    join sourceforge (or whatever we go for)
    svn add your-new-contribution # and all the files in it
    svn commit # with a pre-commit validation
         # ideally, the pre-commit validation would not allow committing if
         # any package fails some of the tests after your change that were
         # successful before your change

    It must be easy for a Manarchive package to depend on other Manarchive
    packages (at the current Manarchive revision; no version spaghetti,
    please)

   In particular, contributing to lib_tools is indeed this easy:

    # to add your new_module to lib_tools:
    cd packages/lib_tools/src
    svn add new_module.m
    echo ":- import_module new_module." >> lib_tools.m

    # to add a testcase, compile and run it
    cd packages/lib_tools/tests
    svn add test_new_module.m
    ../../../tools/runtest test_new_module.m
      # this will compile both the library, as well as test_new_module,
      # it will also run the test and compare its output against
      #    test_new_module.exp


Manarchive Rules:
=================

Manarchive will soon enforce these rules:

1. Anything can be contributed, provided no name-clashes happen.

2. People are kindly asked to stick to coding style of the package they are
   modifying. Bringing your own package, you can bring your own style.

2. As soon as a contributor has time, the package should be upgraded to
   "partially_tested" status: Tested packages must contain a non-empty set of
   tests -- each consisting of a mercury program and expected output (or more
   outputs one of which must succeed).

3. As soon as a contributor has time, the package should be upgraded to
   "has_example" status: Exemplified packages must contain a non-empty set of
   examples -- essentially like test programs with expected output, but intended
   for users to read.

4. If a contributor has abundance of free time, he/she might wish to upgrade a
   package to "fully_tested" status: Fully tested packages must contain a single
   mercury program (with a set of expected inputs and corresponding expected
   outputs) that actually checks every part of the package. 'mcov' will be used
   to check the fully_tested status.


Formalized Package Status:
==========================

For each release of each package included in Manarchive, we report
package_status describing:

- tests summary (if all tests passed etc.)
- level of documentation (assessed by the author)
- presence of any examples to use the package


Credits:
========

Ondrej Bojar (obo@cuni.cz)
Peter Ross (pro@missioncriticalit.com)
Ian MacLarty (maclarty@csse.unimelb.edu.au)