mirror of
https://github.com/keymanapp/keyman.git
synced 2026-09-21 07:07:39 +00:00
afd4d7dcc9
Env var `APPSTORECONNECT_PROVIDER` is unused, so remove it from docs and requirements. Refresh the build and setup docs to reflect modern XCode requirements more accurately and clarify use of `--quick` option for `install`. Test-bot: skip
138 lines
5.1 KiB
Markdown
138 lines
5.1 KiB
Markdown
# Keyman for macOS
|
|
|
|
## Prerequisites
|
|
See [build configuration](../docs/build/index.md) for details on how to configure your build environment.
|
|
|
|
## Keyman for macOS Development
|
|
|
|
Keyman for macOS can be built from a command line (preferred) or Xcode.
|
|
|
|
### Setting up your code signing and notarization environment.
|
|
|
|
With macOS 10.14 and later, Keyman must be notarized in order to be permitted to
|
|
interact with keyboard input. You have two options for local builds:
|
|
|
|
1. You can disable security checks for the system with the command:
|
|
|
|
`sudo spctl --master-disable`
|
|
|
|
This has obvious security implications and the risk is up to you. However,
|
|
builds are much, much, faster than with the alternative option below, and for
|
|
extensive local debugging is far less painful.
|
|
|
|
2. Or, you must sign and notarize every build. This requires an Apple Developer
|
|
Program subscription or access to Developer ID code signing certificates -- a
|
|
self-signed certificate will not work.
|
|
|
|
### Signing and notarizing builds
|
|
|
|
Unless security checks are disabled, Keyman must be signed then notarized by
|
|
Apple, even for local test builds. This requires additional configuration for
|
|
your build environment.
|
|
|
|
1. First, open XCode, Settings, Apple Accounts, `<apple id>`, and select Manage
|
|
Certificates for the identity you wish to use for signing. Find the
|
|
appropriate Development ID certificate.
|
|
|
|
2. Find the SHA-1 hash. To find the certificate in terminal:
|
|
|
|
`security find-certificate -Z -c "<apple-id>" -a`
|
|
|
|
(If you have more than one, you may need to use Keychain Access to
|
|
differentiate). Copy the SHA-1 hash from this command's output.
|
|
|
|
Take note also of the Development Team ID, found in parentheses at the end of
|
|
the `labl` blob line.
|
|
|
|
2. Determine the Apple ID details in order to run a build. You will need to
|
|
create an App-Specific Password at https://appleid.apple.com/.
|
|
|
|
Note: Use your Apple ID for `<Username>` and the app-specific password you
|
|
generated above for `<Password>`. You'll use these in the next step.
|
|
|
|
3. Add the following environment variables to `mac/localenv.sh` (or to
|
|
`~/.bashrc`), replacing with the values you collected in the previous steps:
|
|
|
|
```sh
|
|
export CERTIFICATE_ID=<SHA1-Fingerprint>
|
|
export APPSTORECONNECT_USERNAME=<Username>
|
|
export APPSTORECONNECT_PASSWORD=<Password>
|
|
export DEVELOPMENT_TEAM=<TeamID>
|
|
```
|
|
|
|
### Compiling from Command Line
|
|
|
|
To build Keyman for macOS, do the following:
|
|
|
|
1. Open a Terminal window.
|
|
2. Build using `mac/build.sh clean configure build`
|
|
|
|
Note: If Carthage prompts you to allow it access to your github credentials,
|
|
it's fine to click Deny.
|
|
|
|
### Running Keyman
|
|
|
|
1. Deploy Keyman locally:
|
|
|
|
* Without notarization (requires `spctl --master-disable`), recommended:
|
|
|
|
`mac/build.sh install --quick`
|
|
|
|
This will copy **keyman/mac/Keyman4MacIM/build/Debug/Keyman.app**
|
|
to **~/Library/Input Methods**
|
|
|
|
* With notarization (requires appropriate certificates / Apple Developer
|
|
subscription):
|
|
|
|
`mac/build.sh install`
|
|
|
|
This will notarize the app, signing with your local credentials if not
|
|
already signed, and copy **keyman/mac/Keyman4MacIM/build/Debug/Keyman.app**
|
|
to **~/Library/Input Methods**
|
|
|
|
2. If running for the first time, follow the installation instructions at
|
|
[Install Keyman for macOS].
|
|
|
|
You can also use `mac/build.sh build install [--quick]` to do a single-step
|
|
build, notarize, and deploy (see above for faster options).
|
|
|
|
### Compiling from Xcode
|
|
|
|
To build using Xcode, you will need to build KeymanEngine4Mac first and then
|
|
build Keyman4MacIM. The very _first_ time after getting the source code (and any
|
|
time the Podfile is edited; e.g., to install new pods), you need to go to
|
|
**keyman/mac/Keyman4MacIM** and run `pod install` in Terminal.
|
|
|
|
1. Launch Xcode
|
|
2. Open **keyman/mac/KeymanEngine4Mac/KeymanEngine4Mac.xcodeproj**
|
|
3. Build the project: Product > Build (or Cmd-B)
|
|
4. Open **keyman/mac/Keyman4MacIM/Keyman4MacIM.xcodeproj**
|
|
5. If you do not have signing credentials from the core development team,
|
|
disable code signing in Xcode.
|
|
1. Open the Project Navigator: View > Navigators > Show Project Navigator
|
|
(Cmd-1)
|
|
2. Select Keyman4MacIM and click Build Settings
|
|
3. In the Signing section, change Code Signing Identity to Don't Code Sign.
|
|
This will modify **Keyman4MacIM.xcodeproj**. Do not commit the change.
|
|
6. Build the project. Refer to [Running Keyman](#running-keyman) on how to
|
|
install the app.
|
|
|
|
### Testing
|
|
|
|
The Keyman4Mac project builds a test-bed app that can be used to test keyboards
|
|
without installing the input method. It can also be used as reference for the
|
|
usage of Keyman Engine.
|
|
|
|
Keyman4Mac tests are run using `./build.sh test`.
|
|
|
|
### A note about Homebrew and xcodebuild
|
|
|
|
If you get this error from xcodebuild:
|
|
|
|
`Error: xcode-select: error: tool 'xcodebuild' requires Xcode, but active developer directory is a command line tools instance`
|
|
|
|
Then run this command to fix the build environment:
|
|
|
|
`sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer`
|
|
|
|
[Install Keyman for macOS]: https://help.keyman.com/products/mac/current-version/start/install-keyman
|