source: trunk/ithildin/README @ 791

-------------------------------------------------------------------------------
$Id$
-------------------------------------------------------------------------------
[Table of Contents]:
...0: Preface / Requirements
...1: Getting the source
...2: Compiling
...3: Installing
...4: Running
...5: Help!  It didn't work!
..98: Credits
..99: Contact
-------------------------------------------------------------------------------
[0: Preface / Requirements]:

Reading READMEs from start to finish is usually a good idea.  They tend to
contain a lot of information that is valid/valuable for 99% of users.  That
eing said, I've tried to keep things short and to the point for those of you
who have little patience.  Before you start running the daemon, you should read
the below list of requirements to make sure you've got everything you need.

Requirements:
1. A modern Unix.  At the present time this system is not designed to run on
   anything but Unix and Unix-variant systems.  I will be doing a win32
   version "real soon now" unless Microsoft fires me and I go back to
   working on Unix systems as a dayjob. :)
2. Access to a C compiler, and a few megabytes of space.  You can install this
   system as a regular user, but you will need the compiler and space.
3. At least moderate knowledge of working with files on your system.  You're
   going to need to know how to edit configuration files, run programs, and
   probably move data around.  I've tried to make things fairly clear, but
   YMMV.
4. Python.  The build system used is written in Python.  Most modern systems
   should have this.
4. A module which you wish to run.  Depending on where you got the code from
   (code repository vs. download) you may already have modules.  If you
   downloaded a tarball or zip of this source you do NOT have module source
   lying around, see below for more info on this.

-------------------------------------------------------------------------------
[1: Getting the source]:

The source code for ithildin can currently be retrieved from one of two
places: Subversion (like CVS) or the website.  If you 

* The website is at http://ithildin.org/dist/

* The subversion repository is located at:
  http://svn.ithildin.org/repo/trunk/ithildin
  To check out the latest code from the svn repository, you can do:
  $ svn co http://svn.ithildin.org/repo/trunk/ithildin

  You might wish to browse http://svn.ithildin.org/repo/branches to see if
  you find a branch more to your liking.  The code in 'trunk' is not
  necessarily stable (although I don't commit code that doesn't pass the "It
  built, ship it!" test I do not necessarily test more than that).  If
  you're not sure what you want, get what looks like the latest standard
  branch out of the branches area (it will look like ithildin-x.y and you
  want something where x and y are the highest possible.)

-------------------------------------------------------------------------------
[2: Compiling]:

This system should be relatively straightforward to compile.  You'll need to do
the following:

1) Extract any modules you wish to use in the "modules/" directory.  For
   example let us say you downloaded the "syslog" module package in your home
   directory, you would do:
   $ cd ithildin/modules
   $ tar -zxf ~/syslog.tar.gz
   (NB: not necessary when fetching source via subversion)

2) Copy build/options.default to build/options and then edit build/options.
   The syntax should be straightforward.  You can edit options.default if
   you like, but any future updates will trample that file whereas 'options'
   will never be overwritten either by subversion or future downloads.

3) Run scons!  If you have scons installed you may simply execute scons with
   no options, e.g.:
   $ scons

   Most folks do not have scons installed by default.  Never fear, simply
   use the pre-packaged version in the build directory via:
   $ python build/scons.py

   Help on using scons can be retrieved via the '-h' and '-H' options.

That's it.  If all of this went well, then you can move on to the installing
step.  If not, see section 5.

-------------------------------------------------------------------------------
[3: Installing]:

Installation is, as building, relatively simple, you should be able to install
the system by simply doing:

$ python build/scons.py install

That's it.  If all went well, move on to the next section.  If not, see section
5.

-------------------------------------------------------------------------------
[4: Running]:

You'll probably need to configure the system before you run it.  Look in
$prefix/etc for the various configuration files (where $prefix is where you
set the options file to install code.  If you didn't change it this will be
/usr/local)

-------------------------------------------------------------------------------
[5: Help!  It didn't work!]:

Right now there is no FAQ for "it didn't work" type issues, however you are
invited to file a defect (see the BUGS file) if you believe this is a defect
in the product and not an error in your configuration.  If you're not sure
about it one way or the other please email me or find me on your favorite
chat protocol from below and let me know what the problem is.

-------------------------------------------------------------------------------
[98: Credits]:

See the DEVELOPERS file for a list of developers who are/have been involved
with the project.

-------------------------------------------------------------------------------
[99: Contact]:

You can contact me (the maintainer) using the following details:

Real life: Chip Norkus
Email    : wd@ithildin.org
Address  : If you really really want it just ask.
IRC      : DALnet (occasionally): wd
           EFnet (always on, sometimes idle): wd
AIM      : doubleyewdee
MSN      : wd@teleri.net

Please only e-mail me if you have questions NOT answered in the documentation
here.  Please do not e-mail me about third-party modules or things wholly
unrelated to this project.  Thank you.