Update README and build script

ios/README.md

@@ -5,11 +5,22 @@
 * iOS 8+
 * SwiftLint (`brew install swiftlint`)
 
-### Compiling from Command line
-To build Keyman for iOS, please run the build.sh build script within this folder.
-You will need to run with the command-line argument `-no-codesign` or establish alternate code-signing permissions to complete the build for the final app.
+## Keyman App
 
-To run the app within a simulator after build.sh is completed, "Run" the Keyman scheme/target within Xcode.
+This is the iOS app which is distributed. The source for the app is found in **keyman/**. This project only contains
+the views specific to the Keyman app, while the core functionality is found in KeymanEngine.framework.
+
+### Building
+To build Keyman for iOS, please run the build.sh build script within this folder.
+You will need to run with the command-line argument `-no-codesign` or establish alternate code-signing permissions to
+complete the build for the final app.
+
+To run the app within a simulator after build.sh is completed,
+1. Open **keyman/Keyman/Keyman.xcodeproj** in Xcode.
+2. "Run" the Keyman target within Xcode.
+
+The Keyman app relies on KeymanEngine.framework. `build.sh` builds KeymanEngine.framework and so must be run in the
+initial build and whenever KeymanEngine is modified.
 
 ### Running the app on a physical device
 In order to test any code changes on a physical device, Apple requires that an app be code-signed.  The quickest way to handle this for personal testing:
@@ -28,3 +39,38 @@ In order to test any code changes on a physical device, Apple requires that an a
 - Now, on the device itself, go to **Settings > General > Profiles & Device Management** and give your developer account trusted permissions.
 
 You should then be freely able to test the app on your personal development device.
+
+## KeymanEngine
+
+KeymanEngine is a Swift 4 framework containing the core functionality of Keyman, including
+* The keyboard view and text views that use the Keyman keyboard.
+* Keyboard selection and downloading.
+
+### Building
+To build using command line, run `./build.sh -only-framework`.
+
+To build in Xcode,
+1. Open **engine/KMEI/KeymanEngine.xcodeproj**.
+2. Build the KME-universal target.
+
+The framework will be built to **engine/KMEI/build/(Debug|Release)-universal/KeymanEngine.framework**.
+
+### Linking with KeymanEngine
+1. Add KeymanEngine.framework to 'Linked Frameworks and Libraries' and 'Embedded Binaries' in your project targets.
+
+### Usage
+`TextView` and `TextField` can be used in place of `UITextView` and `UITextField`. These views use Keyman as a keyboard
+and will render with custom fonts. `KeyboardPickerButton` and `KeyboardPickerBarButtonItem` open a view for the user to
+switch keyboards or download new keyboards. `InputViewController` can be subclassed to create a system keyboard.
+
+`Manager` must be set up when your app is initializing. If your app has a system keyboard, you must create an app group
+entitlement, and set `Manager.applicationGroupIdentifier` before any KeymanEngine classes are initialized and before
+`Manager.shared` is used. Also set `Manager.shared.openURL` to `UIApplication.shared.openURL` in your app. Refer to
+`Manager` for more detailed usage and configuration options.
+
+### Samples
+The KeymanEngine project contains a demo app that demonstrates usage of the framework. There are also two sample apps in
+**sample/**. KMSample1 demonstrates use of `TextView` and bundling a keyboard in your app. KMSample2 demonstrates how to
+create a system keyboard.
+
+To build the samples, `cd` into the project directory and run `./build.sh`.

ios/build.sh

@@ -7,11 +7,11 @@
 verify_on_mac
 
 display_usage ( ) {
-    echo "build.sh [-clean] [-no-kmw] [-libKeyman] [-no-codesign] [-no-archive] [-no-build]"
+    echo "build.sh [-clean] [-no-kmw] [-only-framework] [-no-codesign] [-no-archive] [-no-build]"
     echo
     echo "  -clean                  Removes all previously-existing build products for KMEI and the Keyman app before building."
     echo "  -no-kmw                 Uses existing keyman.js, doesn't try to build"
-    echo "  -libKeyman              Builds only KMEI for its libKeyman resources; does not attempt to build the app."
+    echo "  -only-framework         Builds only the KeymanEngine framework; does not attempt to build the app."
     echo "  -no-codesign            Disables code-signing for the Keyman application, allowing it to be performed separately later."
     echo "                          Will not construct the archive and .ipa.  (includes -no-archive)"
     echo "  -no-archive             Bypasses the archive and .ipa preparation stage."
@@ -60,7 +60,7 @@ while [[ $# -gt 0 ]] ; do
             display_usage
             exit 0
             ;;
-        -libKeyman)
+        -only-framework)
             DO_KEYMANAPP=false
             ;;
         -no-codesign)

ios/samples/build_common.sh

@@ -14,13 +14,13 @@ display_usage ( ) {
     echo "build.sh [-no-update] | [-lib-build] | [-lib-ignore] | [-clean]"
     echo
     echo "  -clean          Removes all previously-existing build products for this project before building."
-    echo "  -no-update      If an in-place copy of libKeyman exists, does not seek out an updated copy."
+    echo "  -no-update      If an in-place copy of KeymanEngine.framework exists, does not seek out an updated copy."
     echo "  -lib-build      Actively rebuilds KMEI before copying its build products to project resources."
-    echo "  -lib-nobuild    Prevents the build script from building libKeyman under any circumstances."
+    echo "  -lib-nobuild    Prevents the build script from building KeymanEngine under any circumstances."
     echo "  -no-codesign    Performs the build without code signing."
     echo "  -debug          Sets the configuration to debug mode instead of release."
     echo
-    echo "  If no settings are specified this script will grab a copy of the most recent build of libKeyman,"
+    echo "  If no settings are specified this script will grab a copy of the most recent build of KeymanEngine,"
     echo "  performing an initial build of it if necessary."
     exit 1
 }
@@ -95,23 +95,23 @@ if [ $DO_UPDATE = true ]; then
     verify_KMEI
 
     if [ $ALLOW_KMEI_BUILD = true ] && [ $FORCE_KMEI_BUILD = false ] && [ $KMEI_BUILD_EXISTS = false ]; then
-        echo "Previous libKeyman build information is unavailable."
+        echo "Previous KeymanEngine build information is unavailable."
         FORCE_KMEI_BUILD=true
     fi
 
     if [ $FORCE_KMEI_BUILD = true ]; then
-        echo "Building libKeyman..."
+        echo "Building KeymanEngine..."
         base_dir="$(pwd)"
 
         cd $KMEI_BUILD_DIR
-        ./build.sh -libKeyman $KMEI_FLAGS
+        ./build.sh -only-framework $KMEI_FLAGS
         cd $base_dir
     fi
 
     verify_KMEI
 
     if ! [ $KMEI_BUILD_EXISTS ]; then
-      echo "Build failed:  could not build required libKeyman resources."
+      echo "Build failed:  could not build required KeymanEngine resources."
       exit 1
     fi