summaryrefslogtreecommitdiff
path: root/README
diff options
context:
space:
mode:
authorBen Longbons <b.r.longbons@gmail.com>2013-09-23 21:14:37 -0700
committerBen Longbons <b.r.longbons@gmail.com>2013-09-25 17:36:37 -0700
commita15876e7bff0a45b280f177173446a7a5e9f6cdc (patch)
tree242b9e5e2530be557c97888d01c5820f8f572b31 /README
parenta720c75f7bdf0097f3a13f3a04102da78fd95e7b (diff)
downloadtmwa-a15876e7bff0a45b280f177173446a7a5e9f6cdc.tar.gz
tmwa-a15876e7bff0a45b280f177173446a7a5e9f6cdc.tar.bz2
tmwa-a15876e7bff0a45b280f177173446a7a5e9f6cdc.tar.xz
tmwa-a15876e7bff0a45b280f177173446a7a5e9f6cdc.zip
Fill README, add make rules for intermediate files and install to DESTDIR
Also bump the recommended attoconf version
Diffstat (limited to 'README')
-rw-r--r--README254
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).