Document some of the build process.

diff --git a/docs/building.org b/docs/building.org
new file mode 100644 (file)
index 0000000..c13de5f
--- /dev/null
+++ b/docs/building.org
@@ -0,0 +1,77 @@
+* Requirements
+
+Building (for all OSs) is supported on GNU/Linux or Mac OS X. It
+requires several third-party tools. Other Unix operating systems can
+probably be coerced into building with sufficient work. Maybe even
+Windows.
+
+ * Standard Unix tools
+ * GNU Make
+ * Python 2.x
+ * ~zip~, ~unzip~, ~git~, ~wget~
+
+   Hopefully your OS distributor already provides these...
+
+ * Node.js and npm
+   http://nodejs.org and https://www.npmjs.org
+
+   Node.js is used to run unit tests, linters, and some other build
+   scripts. npm is used to download the modules and programs
+   required for this.
+
+ * GraphicsMagick or ImageMagick
+   http://www.graphicsmagick.org or http://imagemagick.org
+
+   This provides ~convert~, a tool for other image format conversions.
+   You probably have this already; it can be found in most GNU/Linux
+   distributions as well as Mac OS X's MacPorts, homebrew, etc.
+
+ * xcftools (or one of its forks)
+   http://henning.makholm.net/software
+   
+   This provides ~xcf2png~, a tool to convert XCF source images to
+   PNGs. This is available prepackaged in most GNU/Linux
+   distributions, but you'll probably need to build it by hand on Mac
+   OS X.
+
+ * libicns (GNU/Linux only)
+   http://icns.sourceforge.net
+     
+   This provides ~icnsutil~, a tool to convert PNGs to the Cocoa icon
+   format. The compatible ~iconutil~ tool comes with Mac OS X.
+
+ * Wine
+   http://winehq.org/
+
+   Building Windows binary packages requires Wine, to run the
+   rcedit.exe tool. It should run without issue in any Wine
+   configuration.
+
+
+* Local Builds
+
+To build the project, you just need to run ~make~. This will generate
+various data files.
+
+To run the test suite, run ~make check~.
+
+Running it locally in your browser may require a local web server due
+to access restrictions placed on filesystem content in some browsers.
+You can install and start one with sensible defaults by running ~make
+serve~.
+
+
+* Distribution
+
+Building distributables requires that the project be in a git
+repository, and that the source you wish to build is checked in. Git's
+index is used to generate version information and base distributable
+archives.
+
+Ideally, this version is also tagged with some human-readable
+identifier; otherwise it is given a version based on the git index
+hash.
+
+** Source
+
+** Binary