summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLuke Shumaker <LukeShu@sbcglobal.net>2013-11-28 00:39:22 -0500
committerLuke Shumaker <LukeShu@sbcglobal.net>2013-11-28 00:39:22 -0500
commit92ce5b8ce36f849b47b72c2e3b315abb6b6767f1 (patch)
treefdf050bb5f88d903ce492345ef36d695902113d1
parentd098384dcf32921625c420d452466df4f5c696ad (diff)
add an INSTALL file
-rw-r--r--INSTALL119
1 files changed, 119 insertions, 0 deletions
diff --git a/INSTALL b/INSTALL
new file mode 100644
index 0000000..f25c466
--- /dev/null
+++ b/INSTALL
@@ -0,0 +1,119 @@
+Installation of libretools is pretty straight-forward. The only
+tricky thing is the weird dependence on the devtools-par source code.
+
+The build system will by default look at `$(topdir)/../devtools-par`
+for the devtools-par source code. This can be changed by adjusting
+the `devtoolsdir` configuration variable, see "Configuration" below.
+
+Once you have the devtools source taken care of, you can have the
+default everything-included install by running:
+
+ $ make
+ # make install
+
+Dependencies
+------------
+
+Unlike a lot of software, run-time dependencies are not required at
+build-time.
+
+Libretools is mostly shell scripts. It very specifically targets
+Parabola GNU/Linux-libre; there are a lot of dependencies, most of
+which are undocumented. Switching away from a GNU user-land is bound
+to cause issues.
+
+## Build dependencies
+
+The "unusual" build-time dependencies are:
+
+ - GNU Make -- other `make`s will not work.
+ - GNU sed -- must support `-r` for ERE; BSD sed uses `-E` for this purpose.
+ - Emacs -- `emacs --batch` is used use Emacs Lisp to process some text.
+ - ronn -- A markdown-to-manpage converter
+
+At this time, the build system dos not support not building the
+documentation; ronn is required.
+
+Additionally, other usual "core utilities" are required:
+
+ cat, chmod, cp, echo, false, find, install, ln, msguniq, rm, tr,
+ xgettext
+
+Also, `/bin/sh` must support `{brace,expansion}`. If it doesn't, find
+a shell that does, and configure `make` to use it. Though, because
+libretools is mostly shell scripts, if you deviate too much from a GNU
+command-line environment, I suspect that you will run into more
+issues. If I were targeting anything other than Parabola, this would
+be a bigger issue.
+
+## Test suite dependencies
+
+If you wish to run the test suite, you will need the "roundup" shell
+unit testing program. On Parabola GNU/Linux-libre it is called
+"sh-roundup". If your operating system doesn't have it, it is
+available at <http://bmizerany.github.io/roundup/>.
+
+## Run-time dependencies
+
+Being mostly shell scripts, many external program are used. Anything
+that is included when installing the `base` package group on Parabola
+GNU/Linux, I consider an implicit dependency. If something isn't used
+now, that doesn't mean it won't be in the future.
+
+On top of that, the following dependencies are also needed:
+
+librelib subpackage:
+ - wget
+gitget subpackage:
+ - librelib (provided)
+ - git
+main libretools subpackage:
+ - librelib (provided)
+ - gitget (provided, only needed for `createworkdir`)
+ - arch-install-scripts
+ - ssh client (OpenSSH, only needed for `librerelease`
+ - rsync
+ - subversion
+ - tokyocabinet
+libretools-mips64el subpackage:
+ - libretools (provided)
+ - git
+
+Configuration
+-------------
+
+This is not a GNU package, there is no `./configure` script.
+
+There are two ways to set configuration variables:
+ 1. Edit config.mk
+ 2. Pass `VARIABLE=VALUE` to `make`
+
+The configuration variables mostly match GNU packages, but default
+values differ; libretools installs to `prefix=/usr` by default instead
+of GNU's `prefix=/usr/local`.
+
+Building and installing subpackages
+-----------------------------------
+
+There are several subpackages you can build and install. This is done
+by running:
+
+ $ make build-${package}
+ # make install-${package}
+
+respectively. In addition to `build` and `install`, the activities
+you can do are:
+
+ - `copy` -- copy necessary files from the devtools-par source code
+ - `build` -- build all programs and files
+ - `install` -- install everything
+ - `clean` -- remove generated files
+ - `pot` -- generate gettext portable object template files.
+
+The subpackages you can run these on are:
+
+ - doc -- The non-manpage documentation
+ - libretools -- The main libretools package
+ - libretools-mips64el -- Programs useful for porting to mips64el
+ - librelib -- generic libraries included
+ - gitget -- A git downloader