# Keyman for iOS

## Prerequisites
See [build configuration](../docs/build/index.md) for details on how to configure your build environment.

## Keyman App
The source for our published iOS Keyman app is found within the **keyman/** subdirectory. 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 **keymanios.xcworkspace** in Xcode.
2. Run the Keyman target.

The Keyman app relies on KeymanEngine.framework, which will automatically be rebuilt by Xcode whenever it is changed.

### 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.  (Note that code-signing is not necessary for Simulator runs.)  The quickest way to handle this for personal testing:

- Open Xcode and the settings for the Keyman target.
- Establish personal code-signing permissions.
  - Go to the **General** tab and enable "Automatically manage signing" and select your "Personal Team."
  - Change the "Bundle Identifier" for both the Keyman and SWKeyboard targets to something personal and unique.
  - Afterward, swap to the **Capabilities** tab, remove the existing "App Groups", and define your own unique group for the Keyman target.
  - Then, make the "App Group" settings of SWKeyboard match those of Keyman.
  - Perform a find and replace for the group identifier "group.KM4I" and with your selected unique group name.
  - Correct any further error messages Xcode presents you with.
  - **Note**:  All changes for this step (code-signing permissions, app groups, bundle identifier, etc) must be reverted to the original settings for submitted PRs.
- Under the **Product > Destination** Xcode menu, select the device you wish to use for testing.
- Attempt to "Run" Keyman on the device.  The operation should fail, but this step is necessary to continue.
- 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**.

If it doesn't build, and you have upgraded from Xcode 10.0 (or earlier) to 10.1 (or later), it may not
build due to "Could not find any available simulators for iOS" error from Carthage, probably while
building DeviceKit. Xcode 10.1 changed the output format which confuses Carthage. Upgrade Carthage:
```
brew upgrade carthage
brew link --overwrite carthage
```

### 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`.
