Move instructions into cli-c for distribution.

README.md

@@ -194,49 +194,7 @@ Note that in order to build the Android application, you will need to have the A
 
 Go into the `platform-independent/cli-c` directory and run `./build`.  The native command-line client will then be built.
 
-When the build completes, you will have an `mpw` binary you can use.  You can copy it into your `PATH` or use the `./install` script to help you do so.
+For detailed instructions, see [the native CLI instructions](platform-independent/cli-c/README.md).
-
-For example:
-
-    ./build && sudo ./install
-    mpw -h
-
-Normally, this is all you need to do, however note that there are a few dependencies that need to be met, depending on which targets you are building (by default, only the `mpw` target is built):
-
- - `mpw`
-
-The C implementation depends either on `libsodium` or Tarsnap's `scrypt` and `openssl-dev`.
-
-We recommend you install `libsodium`.  If `libsodium` is not installed when `./build` is executed, the script will try to download and statically link Tarsnap's `scrypt` instead.  Tarsnap's `scrypt` depends on you having `openssl-dev` installed.
-
-If you have `mpw_color` enabled (it is enabled by default), the build also depends on `ncurses-dev` to communicate with the terminal.
-
- - `mpw-bench`
-
-This tool compares the performance of a few cryptographic algorithms, including bcrypt.  The `./build` script will try to automatically download and statically link `bcrypt`.
-
- - `mpw-tests`
-
-This tool runs a suite of tests to ensure the correct passwords are being generated by the algorithm under various circumstances.  The test suite is declared in `mpw-tests.xml` which needs to exist in the current working directory when running the tool.  In addition, `libxml2` is used to parse the file, so this target depends on you having it installed when running `./build`.
-
-
-Finally, there are a few different ways you can modify the build process.
-
-To build additional targets, set the `targets` environment variable:
-
-    targets='mpw mpw-tests' ./build
-
-To pass additional compiler arguments, eg. add a library search path, pass them as arguments to the script:
-
-    ./build -L/usr/local/lib
-
-There are a few toggleable features, to change them, pass them as environment variables:
-
-    mpw_color=0 ./build
-
-Currently, there is only one toggleable feature:
-
- - `mpw_color`: [default: 1] Colorized Identicon, depends on `ncurses-dev`.
 
 
 ## Support

platform-independent/cli-c/README.md

@@ -0,0 +1,84 @@
+# Native CLI
+
+This is a command-line terminal interface to the Master Password standard implementation.
+
+To use the app, you'll first need to build it, then install it into your system's PATH.
+
+
+## Building
+
+To build the code to run on your specific system, run the `build` command:
+
+    ./build
+
+Note that the build depends on your system having certain dependencies already installed.
+By default, you'll need to have at least `libsodium`, `libjson-c` and `libncurses` installed.
+
+
+### Details
+
+The build script comes with a default configuration which can be adjusted.  Full details on the build script are available by opening the build script file.
+
+    [targets='...'] [mpw_feature=0|1 ...] [CFLAGS='...'] [LDFLAGS='...'] ./build [cc arguments ...]
+
+By default, the build script only builds the `mpw` target.  You can specify other targets or `all` to build all available targets.  These are the currently available targets:
+
+ - `mpw`        : The main app.  It needs: `mpw_sodium`, optionally supports: `mpw_color`, `mpw_json`.
+ - `mpw-bench`  : A benchmark utility.  It needs: `mpw_sodium`.
+ - `mpw-tests`  : An algorithm test suite.  It needs: `mpw_sodium`, `mpw_xml`.
+
+It is smart to build the test suite along with the app, eg.:
+
+    targets='mpw mpw-tests' ./build
+
+The needed and supported features determine the dependencies that the build will require.  The following features exist:
+
+ - `mpw_sodium` : Use Sodium for the crypto implementation.  It needs libsodium.
+ - `mpw_json`   : Support JSON-based user configuration format.  It needs libjson-c.
+ - `mpw_color`  : Show a colorized identicon.  It needs libncurses.
+ - `mpw_xml`    : Support XML parsing.  It needs libxml2.
+
+By default, all features are enabled.  Each feature can be disabled or enabled explicitly by prefixing the build command with an assignment of it to `0` or `1`, eg.:
+
+    mpw_color=0 ./build
+
+As a result of this command, you'd build the `mpw` target (which supports `mpw_color`) without color support.  The build no longer requires `libncurses` but the resulting `mpw` binary will not have support for colorized identicons.
+
+You can also pass CFLAGS or LDFLAGS to the build, or extra custom compiler arguments as arguments to the build script.
+For instance, to add a custom library search path, you could use:
+
+    LDFLAGS='-L/usr/local/lib' ./build
+
+
+## Testing
+
+Once the client is built, you should run a test suite to make sure everything works as intended.
+
+There are currently two test suites:
+
+ - `mpw-tests`     : Tests the Master Password algorithm implementation.
+ - `mpw-cli-tests` : Tests the CLI application.
+
+The `mpw-tests` suite is only available if you enabled its target during build (see "Details" above).
+
+The `mpw-cli-tests` is a Bash shell script, hence depends on your system having Bash available.
+
+
+## Installing
+
+Once you're happy with the result, you can install the `mpw` application into your system's `PATH`.
+
+Generally, all you need to do is copy the `mpw` file into a PATH directory, eg.:
+
+    cp mpw /usr/local/bin/
+
+The directory that you should copy the `mpw` file into will depend on your system.  Also note that `cp` is a POSIX command, if your system is not a POSIX system (eg. Windows) you'll need to adjust accordingly.
+
+There is also an `install` script to help with this process, though it is a Bash script and therefore requires that you have Bash installed:
+
+    ./install
+
+After installing, you should be able to run `mpw` and use it from anywhere in the terminal:
+
+    mpw -h
+    mpw google.com

platform-independent/cli-c/install

@@ -45,9 +45,20 @@ fi
 echo
 
 inf "You can also save your user name in ~/.bashrc.  Leave blank to skip this step."
-if MP_FULLNAME=$(ask "Your full name:") && [[ $MP_FULLNAME ]] ; then
+if MPW_FULLNAME=$(ask "Your full name:") && [[ $MPW_FULLNAME ]] ; then
-    printf 'export MP_FULLNAME=%q\n' "$MP_FULLNAME" >> ~/.bashrc
+    printf 'export MPW_FULLNAME=%q\n' "$MPW_FULLNAME" >> ~/.bashrc
+fi
+inf "If you have an askpass program you'd like to use, you can specify it here."
+inf "An askpass program provides a graphical interface for entering things like your master password."
+inf "Leave blank to skip this step and enter passwords using the terminal."
+if [[ ! $MPW_ASKPASS ]] && hash ssh-askpass 2>/dev/null; then
+    MPW_ASKPASS=ssh-askpass
+fi
+if MPW_ASKPASS=$(ask +"$MPW_ASKPASS" "askpass program:") && [[ $MPW_ASKPASS ]] ; then
+    printf 'export MPW_ASKPASS=%q\n' "$MPW_ASKPASS" >> ~/.bashrc
 fi
 echo
 
-inf "To begin using Master Password, type: mpw [site name]"
+inf "Shell features installed."
+inf "To load these convenience features into your already running shell, type: source ~/.bashrc"
+inf "To begin using Master Password, type: mpw -h or mpw my-site-name"