add installation instructions to liblitmus (and 'make help')

Some initial documentation to aid new users get started with compiling
the library.

3 files changed, 62 insertions, 16 deletions

diff --git a/INSTALL b/INSTALL
new file mode 100644
index 0000000..4891f0a
--- /dev/null
+++ b/INSTALL
@@ -0,0 +1,56 @@
+
+Liblitmus Installation Instructions
+===================================
+
+Dependencies
+------------
+
+Liblitmus has no dependencies besides the kernel. During compilation, the
+Makefile will attempt to copy required headers from the kernel source tree into
+the library source tree.
+
+
+Configuration
+-------------
+
+The build system reads a local configuration file named '.config' (just like the
+kernel, but much simpler). There are three variables that affect the
+compilation process:
+
+        LITMUS_KERNEL --- Path (relative or absolute) to the LITMUS^RT kernel
+                          source tree. The default value is
+                          '../litmus2010'. Set this variable if you extracted
+                          the kernel somewhere else.
+
+        ARCH          --- The target architecture. Currently, liblitmus can be
+                          build for i386, x86_64, sparc64, and arm.  The default
+                          value is the host architecture.
+
+        CROSS_COMPILE --- A prefix for the compiler and linker to use. Works
+                          exactly like cross-compiling the kernel. By default,
+                          this variable is not set.
+
+Makefile Targets
+----------------
+
+        all         --- Build the library, all tools, and all tests. This is
+                        the default.
+
+        lib         --- Build only the library.
+
+        help        --- Display this help.
+
+        dump-config --- Report the build configuration. Use this to debug
+                        build problems.
+
+        clean       --- Remove all build files and binaries.
+
+        TAGS        --- Create a TAGS file for emacs. (Requires etags to be
+                        installed.)
+
+        tags        --- Create a tags file for vim. (Requires ctags to be
+                        installed.)
+
+        cscope      --- Create a symbol database for cscope. (Requires cscope
+                        to be installed.)
+
diff --git a/Makefile b/Makefile
index d427e1b..ef2be1f 100644
--- a/Makefile
+++ b/Makefile
@@ -73,7 +73,7 @@ all     = lib ${rt-apps}
 rt-apps = cycles base_task rt_launch rtspin release_ts measure_syscall \
           base_mt_task runtests
 
-.PHONY: all lib clean dump-config TAGS tags cscope
+.PHONY: all lib clean dump-config TAGS tags cscope help
 
 all: ${all} inc/config.makefile
 
@@ -111,6 +111,9 @@ dump-config:
                 AR "${AR}" \
                 obj-all "${obj-all}"
 
+help:
+        @cat INSTALL
+
 clean:
         rm -f ${rt-apps}
         rm -f *.o *.d *.a test_catalog.inc
diff --git a/README b/README
index 656dc14..accdf72 100644
--- a/README
+++ b/README
@@ -54,18 +54,5 @@ Tools and Programs
   of single-threaded real-time tasks.
 
 * base_mt_task
-  Example multi-threaded real-time task. Use as a basis for development.
-
-
-Install
-=======
-The library and the included tools  must be compiled from source.
-Liblitmus uses SCons as the build system. For details see:
-
-          http://www.scons.org/
-
-To compile the library just execute the command 'scons' without
-arguments.
-
-x86_64->ia32 cross compilation is possible by specifying ARCH=i386 on the
-command line or in the environment.
+  Example multi-threaded real-time task. Use as a basis for the development of
+  multithreaded real-time tasks.