chore: fleshed out **FAQ.md** and **INSTALL.md**

Author: synesissoftware

FAQ.md

@@ -16,7 +16,23 @@ it will be used to create one.
 
 ## Q1: "How do I build b64?"
 
-T.B.C.
+See [INSTALL.md](./INSTALL.md) for the recommended **CMake** flow
+(**prepare_cmake.sh**, then **build_cmake.sh**).
+
+For a minimal **C API**-only build with no external dependencies:
+
+```bash
+$ ./prepare_cmake.sh --no-cpp --disable-testing -m
+```
+
+For a full build (including the **C++ API** and tests), install **STLSoft**
+1.11 and **xTests** first, then:
+
+```bash
+$ ./prepare_cmake.sh -m
+```
+
+Execute `$ ./prepare_cmake.sh --help` for the full set of options.
 
 
 ## Q2: "How do I install b64?"
@@ -26,8 +42,35 @@ See [INSTALL.md](./INSTALL.md) for details of how to install **b64**.
 
 ## Q3: "How do I use b64?"
 
-T.B.C.
+Include **b64/b64.h** and link against **libb64** (the **CMake** target is
+`b64::core`). Encode and decode with `b64_encode()` / `b64_decode()` (or the
+`2`-suffixed variants for flags and status codes).
 
+A minimal sketch:
 
-<!-- ########################### end of file ########################### -->
+```c
+#include <b64/b64.h>
 
+#include <stdlib.h>
+
+void example(void)
+{
+    unsigned char const bytes[] = { 1, 2, 3, 4 };
+    size_t const cch = b64_encode(bytes, sizeof(bytes), NULL, 0);
+    char* const enc = (char*)malloc(cch);
+
+    if (NULL != enc)
+    {
+        b64_encode(bytes, sizeof(bytes), enc, cch);
+        /* ... use enc[0 .. cch) ... */
+        free(enc);
+    }
+}
+```
+
+Worked examples live under **examples/c/** and **examples/cpp/**. The **C++
+API** (**b64/b64.hpp**) requires **STLSoft**; see [INSTALL.md](./INSTALL.md)
+and [README.md](./README.md).
+
+
+<!-- ########################### end of file ########################### -->

INSTALL.md

@@ -1,14 +1,162 @@
-# b64 - Install <!-- omit in toc -->
+# b64 - Installation and Use <!-- omit in toc -->
+
+**b64** is a classic-form C/C++ library, insofar as it has implementation
+files in its **src** directory and header files in its **include/b64**
+directory. Thus, once "installed", one must simply include **b64/b64.h**
+(C API) or **b64/b64.hpp** (C++ API), and compile-in or link-in the
+implementation.
+
+The **C API** has no non-standard dependencies. The **C++ API** depends on
+**STLSoft**. Building the project's tests additionally requires **xTests**
+(and optionally recognises **shwild**).
+
 
 ## Table of Contents <!-- omit in toc -->
 
-- [Installing](#installing)
+- [CMake](#cmake)
+- [Bundled](#bundled)
 
 
-## Installing
+## CMake
 
-T.B.C.
+The primary choice for installation is by use of **CMake**.
 
+1. Obtain the latest distribution of **b64**, from
+   https://github.com/synesissoftware/b64/, e.g.
 
-<!-- ########################### end of file ########################### -->
+   ```bash
+   $ mkdir -p ~/open-source
+   $ cd ~/open-source
+   $ git clone https://github.com/synesissoftware/b64/
+   ```
+
+2. Prepare the CMake configuration, via the **prepare_cmake.sh** script.
+
+   For a minimal **C API**-only install (no **STLSoft** / **xTests**
+   required):
+
+   ```bash
+   $ cd ~/open-source/b64
+   $ ./prepare_cmake.sh --no-cpp --disable-testing -v
+   ```
+
+   For a full build including the **C++ API**, examples, and tests, install
+   **STLSoft** 1.11 (and **xTests** for tests) via their own **CMake**
+   scripts first, then:
+
+   ```bash
+   $ cd ~/open-source/b64
+   $ ./prepare_cmake.sh -v
+   ```
+
+   If **STLSoft** is available as a source tree rather than an installed
+   **CMake** package, pass its root with `--stlsoft-root-dir` / `-s`.
+
+   (**Hint**: execute `$ ./prepare_cmake.sh --help` for more information.)
+
+3. Run a build of the generated **CMake**-derived build files via the
+   **build_cmake.sh** script, as in:
+
+   ```bash
+   $ ./build_cmake.sh
+   ```
+
+   (**NOTE**: if you provide the flag `--run-make` (=== `-m`) in step 2 then
+   you do not need this step.)
+
+4. As a check (when testing was not disabled), execute the built unit-test
+   programs via **run_all_unit_tests.sh**, as in:
+
+   ```bash
+   $ ./run_all_unit_tests.sh
+   ```
+
+5. Install the library on the host, via `cmake`, as in:
+
+   ```bash
+   $ sudo cmake --install ${SIS_CMAKE_BUILD_DIR:-./_build} --config Release
+   ```
+
+6. Then to use the library, it is a simple matter as follows:
+
+   1. Assuming a simplest possible program to verify the installation:
+
+      ```c
+      /* main.c */
+      #include <b64/b64.h>
+
+      #include <stdio.h>
+      #include <stdlib.h>
+      #include <string.h>
+
+      int main(void)
+      {
+          unsigned char const bytes[] = { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 };
+          size_t const cch = b64_encode(bytes, sizeof(bytes), NULL, 0);
+          char* const enc = (char*)malloc(cch);
 
+          if (NULL == enc)
+          {
+              return EXIT_FAILURE;
+          }
+
+          b64_encode(bytes, sizeof(bytes), enc, cch);
+
+          printf("encoded: %.*s\n", (int)cch, enc);
+
+          free(enc);
+
+          return EXIT_SUCCESS;
+      }
+      ```
+
+   2. Compile your project against **b64**:
+
+      Due to the installation step (step 5 above) there is no requirement
+      for an explicit include directory for **b64**:
+
+      ```bash
+      $ cc -c main.c
+      ```
+
+   3. Link your project against **b64**:
+
+      Due to the installation step (step 5 above) there is no requirement
+      for an explicit library directory for **b64**:
+
+      ```bash
+      $ cc main.o -lb64
+      ```
+
+   4. Test your project:
+
+      ```bash
+      $ ./a.out
+      encoded: AQIDBAUGBwgJCg==
+      $
+      ```
+
+   Consumers that use **CMake** may instead depend on the installed package:
+
+   ```cmake
+   find_package(b64 REQUIRED)
+   target_link_libraries(your_target PRIVATE b64::core)
+   ```
+
+   Use of **b64/b64.hpp** additionally requires **STLSoft**
+   (`find_package(STLSoft REQUIRED)`).
+
+
+## Bundled
+
+**b64** is small enough that it is commonly bundled into other projects
+(for example **Pantheios**). In that case:
+
+* add **b64**'s **include** directory to your project's include path;
+* compile **src/b64.c** into your build (or link a previously built
+  **libb64**); and
+* `#include <b64/b64.h>` (or **b64/b64.hpp** if the **C++ API** and
+  **STLSoft** are available).
+
+
+<!-- ########################### end of file ########################### -->