Documentation update.

builds/android/README.md

@@ -6,10 +6,24 @@ The last known NDK is automatically downloaded, if not specified otherwise.
 
 ## Configuration
 
-This project is tested against Android NDK version r25, but should
+Basically, LIBZMQ build for Android, relies on exported variables.
+Provided build scripts can mainly be used like
+
+### Basics
+
+    export XXX=xxx
+    export YYY=yyy
+    ...
+    cd <libzmq>/builds/android
+    ./<build_script>
+
+
+### Android NDK
+
+LIBZMQ is tested against Android NDK version r25, but should
 support older ones too.
 
-This project uses NDK `android-ndk-r25`, by default, but you can specify
+By default, LIBZMQ uses NDK `android-ndk-r25`, but you can specify
 a different one:
 
     export NDK_VERSION=android-ndk-r23c
@@ -18,7 +32,7 @@ If you already have installed your favorite NDK somewhere, all you have to
 do is to export and set NDK_VERSION and ANDROID_NDK_ROOT environment
 variables, e.g:
 
-    export NDK_VERSION=android-ndk-r23b
+    export NDK_VERSION="android-ndk-r23b"
     export ANDROID_NDK_ROOT=$HOME/${NDK_VERSION}
 
 **Important:** ANDROID_NDK_ROOT must be an absolute path !
@@ -38,14 +52,34 @@ To specify the build directory set the environment variable below:
 
 **Important:** ANDROID_BUILD_ROOT must be an absolute path !
 
-All libraries will be generated under:
+### Android build folder
+
+All Android libraries will be generated under:
 
     ${ANDROID_BUILD_DIR}/prefix/<arch>/lib
 
-where <_arch_> is one of `arm`, `arm64`, `x86` or `x86_64`.
+where <arch> is one of `arm`, `arm64`, `x86` or `x86_64`.
 
-You can also check configuration variables in `build.sh` itself, in its
-"Configuration & tuning options" comment block.
+### Android build cleanup
+
+You can build your own Android libraries, and place them under
+${ANDROID_BUILD_DIR}/prefix/<arch>/lib, but then, you'll need to
+indicate the build scripts to not clean this folder, with the 
+help of ANDROID_BUILD_CLEAN
+
+    ANDROID_BUILD_CLEAN=no
+
+### Dependencies
+
+By default, dependencies are stored under /tmp/tmp-deps, but you
+can specify another folder with the help of ANDROID_DEPENDENCIES:
+
+   ANDROID_DEPENDENCIES_DIR=${HOME}/my_dependencies
+
+If you place your own dependency source trees there, you'll need
+to specify ANDROID_BUILD_CLEAN=no too.
+
+### Cryptographic configuration
 
 The variable CURVE accepts 3 different values: 
 
@@ -53,6 +87,11 @@ The variable CURVE accepts 3 different values:
     "libsodium" : LIBZMQ is built with LIBSODIUM encryption support (see below).
     "tweetnacl" : LIBZMQ is build with embedded encryption support.
 
+### Other configuration variables
+
+You can also check configuration variables in `build.sh` itself, in its
+"Configuration & tuning options" comment block.
+
 ## LIBSODIUM
 
 LIBSODIUM is built along with LIBZMQ, when CURVE="libsodium".
@@ -69,7 +108,7 @@ official STABLE branch.
 See chapter [Configuration](#configuration) for configuration options and
 other details.
 
-Select your prefered parameters:
+Select your preferred parameters:
 
     export XXX=xxx
     export YYY=yyy
@@ -77,11 +116,28 @@ Select your prefered parameters:
 
 And, in the android directory, run:
 
+    cd <libzmq>/builds/android
     ./build.sh [ arm | arm64 | x86 | x86_64 ]
 
 Parameter selection and the calls to build.sh can be located in a
 SHELL script, like in ci_build.sh.
 
+## CI build 
+
+Basically, it will call build.sh once, for each Android target.
+
+This script accepts the same configuration variables, but some are set
+with different default values. For instance, the dependencies are not
+downloaded or cloned in /tmp/tmp-deps, but inside LIBZMQ clone.
+
+It can be used in the same way than build.sh
+
+    export XXX=xxx
+    export YYY=yyy
+    cd <libzmq>/builds/android
+    ./ci_build.sh
+
+
 ## Dockerfile
 
 An example of Docker file is provided, for Ubuntu 22.04