Fill README, add make rules for intermediate files and install to DESTDIR

Also bump the recommended attoconf version

1 files changed, 253 insertions, 1 deletions

diff --git a/README b/README
index 78cf174..7a6edfc 100644
--- a/README
+++ b/README
@@ -1,2 +1,254 @@
-For usage instructions, see:
+This is TMWA, an MMORPG server used by The Mana World that uses a protocol
+based on one of many projects that foolishly chose the name "Athena".
+Specifically, it was forked from eAthena, a Ragnarok Online clone, in 2004.
+
+TMWA is maintained in conjunction with The Mana World, but is not tied to
+it. However, please read the note about server-data below.
+
+
+For user instructions, see:
 http://wiki.themanaworld.org/index.php/How_to_Develop
+
+
+The rest of this file contains information relevant only to
+1. Distributors.
+2. Contributors.
+
+
+TMWA has been maintained by o11c (Ben Longbons) since early 2011 or so.
+Before that, it never really had a proper maintainer, since everyone
+thought that ManaServ was going to be the thing. But it won't ever be.
+
+TMWA has a bugtracker: https://github.com/themanaworld/tmwa/issues
+But it's probably worth getting on IRC first:
+irc://chat.freenode.net/tmwa
+https://webchat.freenode.net/?channels=#tmwa
+
+Note that this channel is *only* for technical discussion of TMWA (and
+attoconf), not general chat or TMW content development.
+
+I'm active in the Pacific timezone, but I might not have internet access
+all the time. I'm usually never AFK longer than 48 hours; when there is an
+exception, I always tell the content devs who also idle there.
+
+(TODO put this file in some sort of markup - github likes .md)
+
+
+1. Distributors.
+# random not-quite-YAML
+platform dependencies:
+  architecture:
+    tested: x86 and (finally!) amd64; possibly x32
+    required: little-endian (for now)
+  operating system:
+    known bad: Linux 2.6.26 and earlier
+    maintained: Linux 3.2 and later
+    likely to break: Cygwin, BSD
+  filesystem:
+    must support symlinks
+build dependencies:
+  C library:
+    recommended: glibc 2.17 or higher
+    supported: glibc 2.13
+    known bad: glibc 2.8 or below
+    unsupported: anything that's not glibc
+  C++ compiler:
+    required: g++ 4.6.1 or higher
+    recommended: g++ 4.7.2 or higher
+    likely to work: clang++ 3.2 or higher
+  C++ library:
+    recommended: libstdc++ to match g++; may need patch for clang++
+    untested: libc++
+  flex:
+    tested: 2.5
+  bison:
+    tested: 2.7
+    bad: 2.3
+  attoconf:
+    special: see below
+runtime dependencies:
+  glibc:
+    depends on what it was built against
+  libstdc++:
+    depends on what it was built against
+instructions:
+  configuration:
+    ./configure --disable-compat-symlinks
+    (Takes most of the options GNU Autoconf's configure does - I won't
+        repeat the output of ./configure --help here.)
+    (--prefix=/usr, not --prefix usr, in order to prevent an ambiguity.
+        "In the face of ambiguity, refuse the temptation to guess.")
+    (Out-of-tree builds work.)
+    (Note that there is no option to disable dependency tracking, as it
+        is also used to generate link information. There is also no option
+        to ignore unknown options - I refuse to lie.)
+  build:
+    make -jN
+  build test:
+    make test
+    (Not really useful yet. Requires source of Google Test.)
+  install:
+    make install DESTDIR=/whatever
+    (See "what is installed" below)
+  install test:
+    not implemented
+
+Note about attoconf:
+  TMWA's ./configure script is implemented using a python package
+  'attoconf', which I wrote over a weekend after reading GNU autoconf's
+  documentation and realizing that it was 1. insane, and 2. still trying
+  to solve the wrong sort of problem.
+
+  Currently, attoconf's API is still in the "experimental" stage, so the
+  real rule is "does ./configure work?".
+  When it gets to 1.0, it will start guaranteeing compatibility.
+
+  Attoconf is available at https://github.com/o11c/attoconf/ and is a
+  well-behaving python package.
+
+  Attoconf requires Python 2.7; a port to Python 2.6 is doable with a bit
+  of work, but it is not known if this would benefit anybody.
+
+  If you're Arch - you broke Python for us all, you clean up your own mess.
+  Patches to call a nonexistent /usr/bin/python2 will NOT be accepted.
+
+What is installed:
+  Overview:
+    Currently, 'make install' installs 5 binaries. Depending on how it is
+    configured, it may also install 5 symlinks for the old names. As a
+    distributor, though, you don't want that, and they will go away soon.
+
+    In future there may be data and configuration files, and 'make install'
+    will offer subtargets (make install-exec) as appropriate.
+
+    The 4 main programs below are typically running on the same machine,
+    though in theory they may be configured to run on different machines
+    in a fast LAN. Also, the internal protocol between the programs is
+    subject to change without notice, so they *must* be upgraded
+    simultaneously.
+
+    All of these programs currently read their config files relative to the
+    current working directory; this is the only thing that makes sense
+    since the files are dependent on the server-data.
+
+
+  tmwa-monitor:
+    Formerly known as eathena-monitor.
+
+    An unmaintained tool whose job was to keep restarting the servers
+    every time they crashed. It still builds in case anyone was using it,
+    but it proved inflexible and has't really been kept up-to-date with our
+    (TMW's) server-data, and besides, the server doesn't crash much now.
+
+    At some point I plan to rewrite it and ship a new conf file, unless
+    everyone agrees to use systemd, in which case I maybe can use that.
+
+    In the mean time, there is a run-all script in the server-data repo
+    that starts the appropriate server for that config. On the main server,
+    we instead start the servers (and bots) individually in a tmux.
+
+  tmwa-admin:
+    Formerly known as ladmin ("local").
+
+    This is an essential tool to maintain the server's flatfile "databases".
+    It doesn't actually touch the files directly, just connects to
+    tmwa-login.
+
+    Even when everything is rewritten to use SQL, it will be kept, if just
+    to keep a consistent interface. In fact, if we use SQLite we *can't*
+    edit the databases independently. This wouldn't be a problem with
+    Postgres, but people seem to think it's hard to install (that's not my
+    experience on Debian though. Did they ever try themselves, or are they
+    just repeating what they've heard?)
+
+  tmwa-login:
+    Formerly known as login-server.
+
+    User-facing server to deal with account checks.
+
+    Also accepts internal connections from tmwa-admin and tmwa-char,
+    subject to a plaintext password (and for tmwa-admin, also an IP check).
+
+  tmwa-char:
+    Formerly known as char-server.
+
+    User-facing server to deal with character persistence.
+
+    Connects to tmwa-login; also takes internal connections from tmwa-map.
+
+    Note that it is fully supported for more than one tmwa-char to connect
+    to the same tmwa-login; the client will be presented with a list of
+    "worlds" before leaving the login-server.
+
+  tmwa-map:
+    Formerly known as map-server.
+
+    Connects to tmwa-char.
+
+    It is technically possible for more than one tmwa-map to connect to
+    a single tmwa-char, but this is poorly supported by our current config
+    and moderation tools.
+
+  about server data:
+    Just having the binaries is not enough: you also need a complete set of
+    content: config files, game scripts, savefiles, and client updates.
+
+    A web server to serve the updates is also strongly recommended, as even
+    developers get annoyed when wushin makes us work straight from his
+    client-data repo.
+
+    Currently, there is only *one* set of server data that is known to be
+    compatible with TMWA: https://github.com/themanaworld/tmwa-server-data
+
+    The only recommended way of using this is by following the instructions
+    in the "How to Develop" article. These instructions are only designed
+    for people contributing to TMW itself, not to people trying to start
+    a fork - we know all forks are doomed to be unsuccessful anyway, so
+    please don't split the development effort, and you can't split the
+    player community.
+
+    In particular, the instructions do NOT provide information on how to
+    secure a server by changing all the default passwords.
+
+    There are 3 other known sets of complete server data: regional ones
+    for Germany and Brasil, and Evol. Evol requires their own fork of
+    the tmwa server (for some reason they don't like me to call it evola),
+    and nobody seems to know of the foreign servers are keeping active.
+
+    Note also that The Mana World has not investigated the copyright status
+    of other sets of server data.
+
+
+2. Contributors.
+The most important thing if you want to help improve TMWA is *talk* to me.
+No, wait, that's the second most important thing.
+
+The real most important thing if you want to help improve TMWA is that it's
+*work*. You can't just stop by and chat for a few hours and help at all.
+If you're going to work on TMWA, you have to be work months in the future.
+
+TMWA was terrible when I got it, and I've only fixed enough to make it
+sane, not pretty. Even a minimal change is likely to touch the whole tree,
+so merge conflicts are a constant problem.
+
+That said, there *are* several tasks that I could use help with. Several
+essential tasks have been left undone just because they don't conflict with
+the main body of my work.
+
+But I do not want someone who will just work for a few hours, go to bed,
+then never return. I have wasted far too many hours answering their
+questions. If you're going to help, you have to actually *help*.
+
+The following skills are good to know required for various tasks:
+  - ability to read
+  - ability to write
+  - ability to notice error messages
+  - ability to solve your own problems
+  - willingness to accept review of your changes. It's not personal if I
+    say your work is wrong, I'm just seeing more than you do, and tiny
+    details are often incredibly important.
+  - familiarity with gdb
+  - Python (A low entry barrier, but Python alone is not enough for the
+    tasks. Particularly, reread the bit about review.)
+  - C++11 (Not a low entry barrier. I'm not really expecting help with this,
+    and since this is conflict heavy, please do the other tasks first).