diff --git a/android/README.md b/android/README.md index 89cf55db67..c7dd245af8 100644 --- a/android/README.md +++ b/android/README.md @@ -1,78 +1,18 @@ # Keyman for Android & Keyman Engine for Android ## Prerequisites -* Android Studio 4.1+ -* Java SE Development Kit 8 -* [Node.js](https://nodejs.org/) 14.17+ (for building KeymanWeb) -* [Pandoc](#Install-Pandoc) for generating offline help - -## Install Java -It is recommended to use openJDK because of oracle license issues. -Tested with latest release for openJDK 8 from -https://github.com/ojdkbuild/ojdkbuild - -1. Download and unpack the zip archive -2. On on windows: use the default java path C:\Program Files\Java to avoid error message "Error 0x80010135 Path Too Long". -3. Aso set an environment variable for JAVA_HOME e.g C:\Program Files\Java\openjdk-1.8.0.232-1 +See [build configuration](../docs/build/index.md) for details on how to configure your build environment. ## Keyman Minimum Android Requirements Keyman for Android has a minSdkVersion of 21 for [Android 5.0 Lollipop](https://developer.android.com/about/versions/lollipop) -## Setup Android Studio - -1. Download [Android Studio](https://developer.android.com/studio/index.html) and install with these [instructions](https://developer.android.com/studio/install.html). -2. For Windows users, set environment variable **ANDROID_HOME** to the location of your Android SDK. The default installation location is **C:\Users\\[USER]\AppData\Local\Android\sdk** where [USER] is your username. You may need to log out and log back in to take effect. - -For MacOS/Linux users, add the following to **~/.bashrc** or **~/.bash_profile** -```bash -export ANDROID_HOME=$HOME/Android/Sdk -export PATH=$PATH:$ANDROID_HOME/tools -``` -For MacOS users, add the following (adjusted appropriately) to **~/.bashrc** or **~/.bash_profile** if your Java version is too strange for gradlew to understand (e.g., 11.0.2) -```bash -export JAVA_HOME=$(/usr/libexec/java_home -v 1.8) -echo $JAVA_HOME #should output: /Library/Java/JavaVirtualMachines/jdk1.8.0_201.jdk/Contents/Home -``` -3. For Windows users, from a Git Bash Prompt window, cd to the **sdk/tools/bin** folder and accept all the SDK license agreements -``` -yes | ./sdkmanager.bat --licenses -``` -For MacOS users, from a Terminal window, cd to the **~/Library/Android/sdk/tools/bin** folder and accept all the SDK license agreements -```bash -yes | ./sdkmanager --licenses -``` -4. If you plan to test on a physical device via USB, install the appropriate [OEM USB drivers](https://developer.android.com/studio/run/oem-usb.html) -5. Install [Java SE Development Kit](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html) - ## Keyman for Android Development Keyman for Android (formerly named KMAPro) can be built from a command line (preferred) or Android Studio. Building Keyman Web is a precursor for compiling KMEA, so verify your system has all the [Minimum Web Compilation Requirements](../web/README.md#minimum-web-compilation-requirements) -### Install JQ -jq 1.6+ is used during the build process to determine the latest versions of the default keyboard (sil_euro_latin.kmp) and lexical-model (en.nrc.mtnt.model.kmp) packages to download. For builds on Windows, jq is already included in `/resources/build/` - -On Linux -`sudo apt install jq` - -### Install Pandoc -Pandoc is used during the build process to generate the app's offline help. -Install from https://pandoc.org/installing.html - ### Crash Reporting Keyman for Android uses [Sentry](https://sentry.io) for crash reporting at a server https://sentry.keyman.com. The analytics for Debug are associated with an App Bundle ID `com.tavultesoft.kmapro.debug`. - -#### Setting up sentry-cli -Contact the Keyman team if you need access to sentry.keyman.com for development. -You will also need to install [sentry-cli](https://docs.sentry.io/cli/installation/) for uploading Debug symbols. -After setting up your personal [Auth token](http://sentry.keyman.com/settings/account/api/auth-tokens/), add the following to **~/.bashrc** -```bash -export SENTRY_AUTH_TOKEN={your Sentry auth token} -export SENTRY_URL=https://sentry.keyman.com -export SENTRY_ORG=keyman -export SENTRY_PROJECT=keyman-android -``` -To validate your configuration, from the `android/` folder run `sentry-cli info`. ### Compiling From Command Line 1. Launch a command prompt and cd to the directory **keyman/android** diff --git a/common/core/desktop/doc/BUILDING.md b/common/core/desktop/doc/BUILDING.md index 6573a32914..db55f6aca0 100644 --- a/common/core/desktop/doc/BUILDING.md +++ b/common/core/desktop/doc/BUILDING.md @@ -1,235 +1,12 @@ # How to build the keyboard processor ## Prerequisites +See [build configuration](../../../../docs/build/index.md) for details on how to configure your build environment. -- Bash (for Windows, included with Git for Windows) -- Python 3 -- Meson build system 0.45+ (0.56+ for WASM) -- ninja 1.8+ -- C++14 or later compiler (VC++ 2019 or later for Windows). -- lib std::fs -- kmcomp (for tests) -- must be added to path -- Rust 1.50+ from (or `cargo` package on Linux) - -For WASM builds: -- Meson build system 0.56+ -- emscripten 2.0.23+ -- WasmPack 0.9.1+ -- ninja 1.10+ for WASM - -### Windows - -* Install Git for Windows: - -* Install Python 3: - - You can get the official Python installer from the official Python site: - - - Ensure you have Python3 correctly installed and can run the command `pip`. - - Ensure that Python 3 is on the path ahead of Python 2 (if installed). - -* Install meson: - - ```bash - python -m pip install meson - ``` - -* Install [ninja](https://ninja-build.org/) 1.10+: - - ```bash - choco install ninja - ``` - -* Install Rust: - - After downloading and running the executable from: - - - Run the command: - - ```bash - rustup target add i686-pc-windows-msvc - rustup target add wasm32-unknown-unknown - ``` - -* Install wasm-pack: - - -* Install Emscripten: - - -* Add emcc to PATH (probably upstream\enscripten) - -#### Windows environment - -On Windows you may need to set `SDKVER` environment variable to the current -Windows SDK version, if it cannot be automatically detected. - -```bash -export SDKVER=10.0.19041.0 -``` - -#### kmcomp - -Note on paths for kmcomp: - -The search path can be edited through System settings / Advanced system settings -/ Environment Variables / User environment variables. - -If you have Keyman Developer installed, kmcomp should be on the path already; -otherwise add `%KeymanDeveloperPath%` to your path. - -If you do not have Keyman Developer installed, add the path where you extracted -the kmcomp archive. - -### Linux - -#### Ubuntu and Debian - -* Install Python - - ```bash - sudo apt install python3 - ``` - -* Upgrade Meson from version included with Python (WASM builds): - - ```bash - sudo apt install meson - ``` - -* Install Rust: - - ```bash - curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh - rustup target add wasm32-unknown-unknown - ``` - -* Install wasm-pack (WASM builds): - - ```bash - curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh - ``` - -* Install Enscripten (including adding to path with `emsdk_env.sh`) (WASM builds): - - -You may also need the `kmcomp` wrapper - see below. - -#### Other Linux distributions - -* Install Python 3 and pip - - You will be able to install a python3 package in any reputable recent version of - linux using its package manager if it's not already installed. Ensure that `pip` - is also installed. - -* Install meson: - - ```bash - python3 -m pip install meson - ``` - -* Install Rust from , then: - - ```bash - rustup target add wasm32-unknown-unknown - ``` - -* Install wasm-pack (WASM builds): - - ```bash - curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh - ``` - -* Install Enscripten (WASM builds): - - -* Add emcc to PATH (probably upstream/enscripten) - -You may also need the `kmcomp` wrapper - see below. - -#### kmcomp - All Linux platforms - -If you want to rebuild keyboards for tests, you need a wrapper `kmcomp` shell -script: - -```bash -#!/usr/bin/env bash -wine `dirname "$0"`/kmcomp.exe "$@" -``` - -Place this in the same folder as you extracted kmcomp.exe, and -`chmod +x kmcomp`. Add the folder to the path (e.g. -`export PATH=/path/to/kmcomp:$PATH`, which you can add to `.bashrc`). - -### macOS - -* Install Python 3 - - You can get the official Python installer from the official Python site: - - -* Install meson: - - ```bash - brew install meson # if you haven't already installed via pip - ``` - -* Install Rust: - - ```bash - curl https://sh.rustup.rs -sSf | sh - rustup target add wasm32-unknown-unknown - ``` - -* Install wasm-pack: - - ```bash - curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh - ``` - -* Install Enscripten (including environment update): - - -#### kmcomp - -If you want to rebuild keyboards for tests, you'll also need WINE: - -```bash -brew tap homebrew/cask-versions -brew install --cask --no-quarantine wine-stable -``` - -And you will also need a wrapper `kmcomp` shell script: - -```bash -#!/usr/bin/env bash -wine64 `dirname "$0"`/kmcomp.exe "$@" -``` - -Place this in the same folder as you extracted kmcomp.exe, and -`chmod +x kmcomp`. Add the folder to the path (e.g. -`export PATH=/path/to/kmcomp:$PATH`, which you can add to `.bashrc`). - -## Building -- all platforms +## Building On all platforms, use `build.sh`. -* To build native libraries and tests: - - ```bash - ./build.sh --debug - ``` - -* To build WASM libraries and tests: - - ```bash - ./build.sh --platform wasm - ``` - * See `./build.sh --help` for more details ## Note on kmcomp diff --git a/docs/build/index.md b/docs/build/index.md new file mode 100644 index 0000000000..bca0627234 --- /dev/null +++ b/docs/build/index.md @@ -0,0 +1,25 @@ +# How to configure your build environment + +Keyman has a wide range of dependencies. We are working to reduce the complexity of setting up a development environment over time, but this document should give you all you need in order to start contributing to Keyman. + +## Development Platforms + +* [Linux - Ubuntu](linux-ubuntu.md) +* [macOS](macos.md) +* [Windows](windows.md) + +## Additional Configuration Documentation + +Additional notes are available in the following documents: + +* [sentry-cli configuration](sentry-cli.md) + +Older notes: + +* [Keyman for Android notes](old/android-notes.md) +* [Keyman for iOS notes](old/ios-notes.md) +* [Keyman for macOS notes](old/macos-notes.md) +* [KeymanWeb notes](old/web-notes.md) +* [Keyman Core Desktop notes](old/core-desktop-notes.md) + +Many folders may also contain other build instructions in README.md files. diff --git a/docs/build/linux-ubuntu.md b/docs/build/linux-ubuntu.md new file mode 100644 index 0000000000..910a3b8d2d --- /dev/null +++ b/docs/build/linux-ubuntu.md @@ -0,0 +1,3 @@ +# Setup your Keyman build environment on Ubuntu + +TODO diff --git a/docs/build/macos.md b/docs/build/macos.md new file mode 100644 index 0000000000..41a45f7ad2 --- /dev/null +++ b/docs/build/macos.md @@ -0,0 +1,101 @@ +# Setup your Keyman build environment on macOS + +## Target Projects + +On macOS, you can build the following projects: + +* Keyman for Android +* Keyman for iOS +* Keyman for macOS +* KeymanWeb + +The following libraries can also be built: + +* Common/Core/Desktop (macOS, wasm targets) +* Common/Core/Web + +The following projects **cannot** be built on macOS: + +* Keyman for Linux +* Keyman for Windows +* Keyman Developer + +## System Requirements + +* Minimum macOS version: macOS Catalina 10.15 or Big Sur 11.0 + +## Prerequisites + +Many dependencies are only required for specific projects. + +* XCode (iOS, macOS) + * Install from App Store + * Accept the Xcode license: `sudo xcodebuild -license accept` + +The remaining dependencies can be installed via script: + `resources/devbox/macos/macos.sh` + +This script will also update your environment to the values in: + `resources/devbox/macos/keyman.macos.env.sh` + +It will also add these environment settings to your `~/.bashrc`. + +These dependencies are also listed below if you'd prefer to install manually. + +## Shared Dependencies + +* Shared: HomeBrew, Bash 5.0+, jq, Python 3, Meson, Ninja, Rust, coreutils, Pandoc + + ```shell + /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" + brew install bash jq python3 meson ninja rustup-init coreutils pandoc rustup-init + ``` + +* Web: node.js, emscripten, wasm-pack, openjdk 8 + + ```shell + brew install node emscripten wasm-pack openjdk@8 + rustup target add wasm32-unknown-unknown + ``` + +* iOS: swiftlint, carthage + + ```shell + brew install swiftlint carthage + ``` + +* macOS: carthage, cocoapods + + ```shell + brew install carthage cocoapods + ``` + +* Android: openjdk 8, Android SDK, Android Studio, Ant, Gradle, Maven + + ```shell + brew install openjdk@8 android-sdk android-studio ant gradle maven + # update path + source ../resources/devbox/macos/keyman.macos.env.sh + # optionally install sdk images + sdkmanager "system-images;android-30;google_apis;armeabi-v7a" + sdkmanager --update + sdkmanager --licenses + ``` + +* kmcomp (optional): WINE + - Required to build keyboards using kmcomp + + ```bash + brew tap homebrew/cask-versions + brew install --cask --no-quarantine wine-stable + ``` + +* sentry-cli (optional) + - Uploading symbols for Sentry-based error reporting + + ``` + brew install getsentry/tools/sentry-cli + ``` + +* Run Android Studio once after installation to install additional components + such as emulator images and SDK updates. diff --git a/docs/build/old/android-notes.md b/docs/build/old/android-notes.md new file mode 100644 index 0000000000..409f0057b2 --- /dev/null +++ b/docs/build/old/android-notes.md @@ -0,0 +1,56 @@ +# Keyman for Android configuration notes + +WARNING: these are old configuration notes. See [index.md](../index.md) for current steps. + +* Android Studio 4.1+ +* Java SE Development Kit 8 +* [Node.js](https://nodejs.org/) 14.17+ (for building KeymanWeb) +* [Pandoc](#Install-Pandoc) for generating offline help + +## Install Java +It is recommended to use openJDK because of Oracle license issues. +Tested with latest release for openJDK 8 from +https://github.com/ojdkbuild/ojdkbuild + +1. Download and unpack the zip archive +2. On windows: use the default java path C:\Program Files\Java to avoid error message "Error 0x80010135 Path Too Long". +3. Also set an environment variable for JAVA_HOME e.g C:\Program Files\Java\openjdk-1.8.0.232-1 + +## Setup Android Studio + +1. Download [Android Studio](https://developer.android.com/studio/index.html) and install with these [instructions](https://developer.android.com/studio/install.html). +2. For Windows users, set environment variable **ANDROID_HOME** to the location of your Android SDK. The default installation location is **C:\Users\\[USER]\AppData\Local\Android\sdk** where [USER] is your username. You may need to log out and log back in to take effect. + +For MacOS/Linux users, add the following to **~/.bashrc** or **~/.bash_profile** + +```bash +export ANDROID_HOME=$HOME/Android/Sdk +export PATH=$PATH:$ANDROID_HOME/tools +``` +For MacOS users, add the following (adjusted appropriately) to **~/.bashrc** or **~/.bash_profile** if your Java version is too strange for gradlew to understand (e.g., 11.0.2) + +```bash +export JAVA_HOME=$(/usr/libexec/java_home -v 1.8) +echo $JAVA_HOME #should output: /Library/Java/JavaVirtualMachines/jdk1.8.0_201.jdk/Contents/Home +``` +3. For Windows users, from a Git Bash Prompt window, cd to the **sdk/tools/bin** folder and accept all the SDK license agreements + +``` +yes | ./sdkmanager.bat --licenses +``` +For MacOS users, from a Terminal window, cd to the **~/Library/Android/sdk/tools/bin** folder and accept all the SDK license agreements +```bash +yes | ./sdkmanager --licenses +``` +4. If you plan to test on a physical device via USB, install the appropriate [OEM USB drivers](https://developer.android.com/studio/run/oem-usb.html) +5. Install [Java SE Development Kit](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html) + +### Install JQ +jq 1.6+ is used during the build process to determine the latest versions of the default keyboard (sil_euro_latin.kmp) and lexical-model (en.nrc.mtnt.model.kmp) packages to download. For builds on Windows, jq is already included in `/resources/build/` + +On Linux +`sudo apt install jq` + +### Install Pandoc +Pandoc is used during the build process to generate the app's offline help. +Install from https://pandoc.org/installing.html diff --git a/docs/build/old/core-desktop-notes.md b/docs/build/old/core-desktop-notes.md new file mode 100644 index 0000000000..4eceb94fd0 --- /dev/null +++ b/docs/build/old/core-desktop-notes.md @@ -0,0 +1,231 @@ +# Common/Core/Desktop configuration notes + +WARNING: these are old configuration notes. See [index.md](../index.md) for current steps. + +- Bash (for Windows, included with Git for Windows) +- Python 3 +- Meson build system 0.45+ (0.56+ for WASM) +- ninja 1.8+ +- C++14 or later compiler (VC++ 2019 or later for Windows). +- lib std::fs +- kmcomp (for tests) -- must be added to path +- Rust 1.50+ from (or `cargo` package on Linux) + +For WASM builds: +- Meson build system 0.56+ +- emscripten 2.0.23+ +- WasmPack 0.9.1+ +- ninja 1.10+ for WASM + +### Windows + +* Install Git for Windows: + +* Install Python 3: + + You can get the official Python installer from the official Python site: + + + Ensure you have Python3 correctly installed and can run the command `pip`. + + Ensure that Python 3 is on the path ahead of Python 2 (if installed). + +* Install meson: + + ```bash + python -m pip install meson + ``` + +* Install [ninja](https://ninja-build.org/) 1.10+: + + ```bash + choco install ninja + ``` + +* Install Rust: + + After downloading and running the executable from: + + + Run the command: + + ```bash + rustup target add i686-pc-windows-msvc + rustup target add wasm32-unknown-unknown + ``` + +* Install wasm-pack: + + +* Install Emscripten: + + +* Add emcc to PATH (probably upstream\enscripten) + +#### Windows environment + +On Windows you may need to set `SDKVER` environment variable to the current +Windows SDK version, if it cannot be automatically detected. + +```bash +export SDKVER=10.0.19041.0 +``` + +#### kmcomp + +Note on paths for kmcomp: + +The search path can be edited through System settings / Advanced system settings +/ Environment Variables / User environment variables. + +If you have Keyman Developer installed, kmcomp should be on the path already; +otherwise add `%KeymanDeveloperPath%` to your path. + +If you do not have Keyman Developer installed, add the path where you extracted +the kmcomp archive. + +### Linux + +#### Ubuntu and Debian + +* Install Python + + ```bash + sudo apt install python3 + ``` + +* Upgrade Meson from version included with Python (WASM builds): + + ```bash + sudo apt install meson + ``` + +* Install Rust: + + ```bash + curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh + rustup target add wasm32-unknown-unknown + ``` + +* Install wasm-pack (WASM builds): + + ```bash + curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh + ``` + +* Install Enscripten (including adding to path with `emsdk_env.sh`) (WASM builds): + + +You may also need the `kmcomp` wrapper - see below. + +#### Other Linux distributions + +* Install Python 3 and pip + + You will be able to install a python3 package in any reputable recent version of + linux using its package manager if it's not already installed. Ensure that `pip` + is also installed. + +* Install meson: + + ```bash + python3 -m pip install meson + ``` + +* Install Rust from , then: + + ```bash + rustup target add wasm32-unknown-unknown + ``` + +* Install wasm-pack (WASM builds): + + ```bash + curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh + ``` + +* Install Enscripten (WASM builds): + + +* Add emcc to PATH (probably upstream/enscripten) + +You may also need the `kmcomp` wrapper - see below. + +#### kmcomp - All Linux platforms + +If you want to rebuild keyboards for tests, you need a wrapper `kmcomp` shell +script: + +```bash +#!/usr/bin/env bash +wine `dirname "$0"`/kmcomp.exe "$@" +``` + +Place this in the same folder as you extracted kmcomp.exe, and +`chmod +x kmcomp`. Add the folder to the path (e.g. +`export PATH=/path/to/kmcomp:$PATH`, which you can add to `.bashrc`). + +### macOS + +* Install Python 3 + + You can get the official Python installer from the official Python site: + + +* Install meson: + + ```bash + brew install meson # if you haven't already installed via pip + ``` + +* Install Rust: + + ```bash + curl https://sh.rustup.rs -sSf | sh + rustup target add wasm32-unknown-unknown + ``` + +* Install wasm-pack: + + ```bash + curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh + ``` + +* Install Enscripten (including environment update): + + +#### kmcomp + +If you want to rebuild keyboards for tests, you'll also need WINE: + +```bash +brew tap homebrew/cask-versions +brew install --cask --no-quarantine wine-stable +``` + +And you will also need a wrapper `kmcomp` shell script: + +```bash +#!/usr/bin/env bash +wine64 `dirname "$0"`/kmcomp.exe "$@" +``` + +Place this in the same folder as you extracted kmcomp.exe, and +`chmod +x kmcomp`. Add the folder to the path (e.g. +`export PATH=/path/to/kmcomp:$PATH`, which you can add to `.bashrc`). + +## Building -- all platforms + +On all platforms, use `build.sh`. + +* To build native libraries and tests: + + ```bash + ./build.sh --debug + ``` + +* To build WASM libraries and tests: + + ```bash + ./build.sh --platform wasm + ``` \ No newline at end of file diff --git a/docs/build/old/ios-notes.md b/docs/build/old/ios-notes.md new file mode 100644 index 0000000000..47fd967f0e --- /dev/null +++ b/docs/build/old/ios-notes.md @@ -0,0 +1,21 @@ +# Keyman for iOS configuration notes + +WARNING: these are old configuration notes. See [macos.md](../macos.md) for current steps. + +## Prerequisites +* Xcode 11 +* iOS 9+ +* SwiftLint (`brew install swiftlint`) +* Carthage 0.37+ (`brew install carthage`) +* Pandoc (`brew install pandoc`) + - Used solely to generate offline help. +* Coreutils (`brew install coreutils`) +* sentry-cli (`brew install getsentry/tools/sentry-cli`) to utilize Sentry-based error reporting +* jq (`brew install jq`) +* `bash` (`brew install bash`) +* Building Keyman Web is a precursor for compiling KMEI, so verify your system has all the [Minimum Web Compilation Requirements](../web/README.md#minimum-web-compilation-requirements), including (but not limited to): + - [Node.js](https://nodejs.org/) 8.9+ (for building the embedded KeymanWeb engine) + - [Java 7+](https://adoptopenjdk.net/releases.html) + +Note that the `brew` command mentioned above is Homebrew, which may be found at https://brew.sh/. +While not strictly necessary, it certainly simplifies installing the prerequisites above. diff --git a/docs/build/old/macos-notes.md b/docs/build/old/macos-notes.md new file mode 100644 index 0000000000..77a83bd038 --- /dev/null +++ b/docs/build/old/macos-notes.md @@ -0,0 +1,17 @@ +# Keyman for macOS configuration notes + +WARNING: these are old configuration notes. See [macos.md](../macos.md) for current steps. + +## Mac Tools Requirements/Setup + +* Install [Homebrew] *technically optional, but highly recommended* +* Install Xcode 12.0+ +* Accept the Xcode license `sudo xcodebuild -license accept` +* Install [Carthage] (`brew install carthage`) *see Homebrew note below* +* Install [cocoapods] (`brew install cocoapods`) +* Install [coreutils] (`brew install coreutils`) + +[Homebrew]: https://brew.sh/ +[Carthage]: https://github.com/Carthage/Carthage/blob/master/README.md +[cocoapods]: https://cocoapods.org/ +[coreutils]: https://www.gnu.org/software/coreutils/ diff --git a/docs/build/old/web-notes.md b/docs/build/old/web-notes.md new file mode 100644 index 0000000000..23ebf26d61 --- /dev/null +++ b/docs/build/old/web-notes.md @@ -0,0 +1,18 @@ +# KeymanWeb configuration notes + +WARNING: these are old configuration notes. See [index.md](../index.md) for current steps. + +## Minimum Web Compilation Requirements + +* [Java 7+](https://adoptopenjdk.net/releases.html) (required by the Google Closure Compiler) + * This can be ignored for Keyman Developer builds. +* A local installation of [Node.js](https://nodejs.org/) v8.9+. + * Builds will call `npm install` to automatically install further necessary build dependencies. + + * Linux users can run the following to update to LTS version of nodejs + +``` +sudo apt-get install python-software-properties +curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash - +sudo apt-get install nodejs +``` diff --git a/docs/build/sentry-cli.md b/docs/build/sentry-cli.md new file mode 100644 index 0000000000..7136bee2c1 --- /dev/null +++ b/docs/build/sentry-cli.md @@ -0,0 +1,15 @@ +# Setting up sentry-cli + +Contact the Keyman team if you need access to sentry.keyman.com for development. +You will also need to install [sentry-cli](https://docs.sentry.io/cli/installation/) for uploading Debug symbols. +After setting up your personal [Auth token](http://sentry.keyman.com/settings/account/api/auth-tokens/), add the following to **~/.bashrc** + +```bash +export SENTRY_AUTH_TOKEN={your Sentry auth token} +export SENTRY_URL=https://sentry.keyman.com +export SENTRY_ORG=keyman +# select the appropriate project here: +export SENTRY_PROJECT=keyman-android +``` + +To validate your configuration, for example for keyman-android, from the `android/` folder run `sentry-cli info`. diff --git a/docs/build/windows.md b/docs/build/windows.md new file mode 100644 index 0000000000..f0f48e0733 --- /dev/null +++ b/docs/build/windows.md @@ -0,0 +1,3 @@ +# Setup your Keyman build environment on Windows + +TODO diff --git a/ios/README.md b/ios/README.md index e79d99884f..49c3d57233 100644 --- a/ios/README.md +++ b/ios/README.md @@ -1,25 +1,9 @@ # Keyman for iOS ## Prerequisites -* Xcode 11 -* iOS 9+ -* SwiftLint (`brew install swiftlint`) -* Carthage 0.37+ (`brew install carthage`) -* Pandoc (`brew install pandoc`) - - Used solely to generate offline help. -* Coreutils (`brew install coreutils`) -* sentry-cli (`brew install getsentry/tools/sentry-cli`) to utilize Sentry-based error reporting -* jq (`brew install jq`) -* `bash` (`brew install bash`) -* Building Keyman Web is a precursor for compiling KMEI, so verify your system has all the [Minimum Web Compilation Requirements](../web/README.md#minimum-web-compilation-requirements), including (but not limited to): - - [Node.js](https://nodejs.org/) 8.9+ (for building the embedded KeymanWeb engine) - - [Java 7+](https://adoptopenjdk.net/releases.html) - -Note that the `brew` command mentioned above is Homebrew, which may be found at https://brew.sh/. -While not strictly necessary, it certainly simplifies installing the prerequisites above. +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. @@ -94,11 +78,3 @@ The KeymanEngine project contains a demo app that demonstrates usage of the fram create a system keyboard. To build the samples, `cd` into the project directory and run `./build.sh`. - -### Compiling the app's offline help -Extra prerequisite: -* `wget` (`brew install wget`) - -The script `build-help.sh` uses the `wget` tool to construct an offline bundle from the current -online version of help on help.keyman.com. When significant changes to help content have been -made, it is advisable to manually re-run this script to update the app's offline content. \ No newline at end of file diff --git a/mac/README.md b/mac/README.md index 7e614cde69..32c59cafe1 100644 --- a/mac/README.md +++ b/mac/README.md @@ -1,13 +1,5 @@ # Keyman for macOS -## Mac Tools Requirements/Setup - -* Install [Homebrew] *technically optional, but highly recommended* -* Install Xcode 12.0+ -* Accept the Xcode license `sudo xcodebuild -license accept` -* Install [Carthage] (`brew install carthage`) *see Homebrew note below* -* Install [cocoapods] (`brew install cocoapods`) -* Install [coreutils] (`brew install coreutils`) ## Keyman for macOS Development @@ -120,9 +112,4 @@ Then run this command to fix the build environment: `sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer` - -[Homebrew]: https://brew.sh/ -[Carthage]: https://github.com/Carthage/Carthage/blob/master/README.md -[cocoapods]: https://cocoapods.org/ -[coreutils]: https://www.gnu.org/software/coreutils/ [Install Keyman for macOS]: https://help.keyman.com/products/mac/current-version/start/install-keyman diff --git a/resources/devbox/macos/keyman.macos.env.sh b/resources/devbox/macos/keyman.macos.env.sh new file mode 100644 index 0000000000..b6fc5b83d8 --- /dev/null +++ b/resources/devbox/macos/keyman.macos.env.sh @@ -0,0 +1,19 @@ +source $HOME/.cargo/env +#echo 'export PATH="/usr/local/opt/openjdk@8/bin:$PATH"' >> ~/.zshrc +#echo 'export PATH="/usr/local/opt/openjdk@8/bin:$PATH"' >> ~/.bashrc +export ANT_HOME=/usr/local/opt/ant +export MAVEN_HOME=/usr/local/opt/maven +export GRADLE_HOME=/usr/local/opt/gradle +export ANDROID_HOME=~/.android +export ANDROID_SDK_ROOT="$HOME/Library/Android/sdk" + +export PATH=$ANT_HOME/bin:$PATH +export PATH=$MAVEN_HOME/bin:$PATH +export PATH=$GRADLE_HOME/bin:$PATH +export PATH=$ANDROID_HOME/tools:$PATH +export PATH=$ANDROID_HOME/tools/bin:$PATH +export PATH=$ANDROID_HOME/platform-tools:$PATH +export PATH=$ANDROID_HOME/build-tools/30.0.3:$PATH +export PATH="/usr/local/opt/openjdk@8/bin:$PATH" + +export JAVA_HOME=/usr/local/opt/openjdk@8 diff --git a/resources/devbox/macos/macos.sh b/resources/devbox/macos/macos.sh new file mode 100755 index 0000000000..a5e7232e46 --- /dev/null +++ b/resources/devbox/macos/macos.sh @@ -0,0 +1,224 @@ +#!/usr/bin/env bash + +set -e +set -u + +## Note: does not use standard build script include +# adjust relative paths as necessary. Note that this will not work in a symlinked path reliably +THIS_SCRIPT="${BASH_SOURCE[0]}" +THIS_DIR=$(dirname "$THIS_SCRIPT") + +# Determine which components to install +REQUIRE_ANDROID=false +REQUIRE_IOS=false +REQUIRE_MACOS=false +REQUIRE_WEB=false + +# Optional components +REQUIRE_KMCOMP=false +REQUIRE_PANDOC=false +REQUIRE_SENTRYCLI=false + +# Parse args +shopt -s nocasematch + +PARAMFOUND=false + +function print_help() { + echo "Usage: macos.sh targets" + echo + echo "The targets parameter determines the platforms and components" + echo "that this script will setup your environment to build." + echo + echo " group targets:" + echo " all build all platform targets" + echo " all-optional build all targets, including optional" + echo + echo " platform targets:" + echo " android ios macos web" + echo + echo " optional targets:" + echo " kmcomp Keyman keyboard compiler" + echo " pandoc Documentation compiler" + echo " sentry-cli sentry.keyman.com debug symbol uploader" + echo + echo "Note: If a target has dependencies, those will automatically" + echo " be included." +} + +while [[ $# -gt 0 ]] ; do + key="$1" + case $key in + --help) + print_help + exit 0 + ;; + android) + REQUIRE_ANDROID=true + PARAMFOUND=true + ;; + ios) + REQUIRE_IOS=true + PARAMFOUND=true + ;; + macos) + REQUIRE_MACOS=true + PARAMFOUND=true + ;; + web) + REQUIRE_WEB=true + PARAMFOUND=true + ;; + kmcomp) + REQUIRE_KMCOMP=true + PARAMFOUND=true + ;; + pandoc) + REQUIRE_PANDOC=true + PARAMFOUND=true + ;; + sentry-cli) + REQUIRE_SENTRYCLI=true + PARAMFOUND=true + ;; + all) + REQUIRE_ANDROID=true + REQUIRE_IOS=true + REQUIRE_MACOS=true + REQUIRE_WEB=true + PARAMFOUND=true + ;; + all-optional) + REQUIRE_ANDROID=true + REQUIRE_IOS=true + REQUIRE_MACOS=true + REQUIRE_WEB=true + REQUIRE_KMCOMP=true + REQUIRE_PANDOC=true + REQUIRE_SENTRYCLI=true + PARAMFOUND=true + ;; + *) + echo "Error: unrecognised parameter." + echo + print_help + exit 1 + ;; + esac + shift +done + +if ! $PARAMFOUND; then + echo "Error: must specify target parameter" + echo + print_help + exit 1 +fi + +# This script will configure your development environment from a bare metal mac install. It should be idempotent. + +echo "This script will configure your macOS computer to build Keyman, installing build tools and prerequisites." +echo "You can also do this yourself following the notes in docs/build/macos.md." +echo +read -p "Press ENTER to start install" + +if $REQUIRE_IOS || $REQUIRE_ANDROID; then + REQUIRE_WEB=true +fi + +if $REQUIRE_IOS || $REQUIRE_MACOS || $REQUIRE_ANDROID; then + REQUIRE_PANDOC=true +fi + +## These components are required by all development toolchains + +# XCode command lines tools will be installed by Brew +# xcode-select --install + +which brew || ( + # Install Homebrew + /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" +) && ( + brew update +) + +## Install devchain components + +BREW_ALL="bash jq python3 meson ninja rustup-init coreutils" +BREW_WEB="node emscripten wasm-pack openjdk@8" +BREW_IOS="swiftlint carthage" +BREW_MACOS="carthage cocoapods" +BREW_ANDROID="openjdk@8 android-sdk android-studio ant gradle maven" + +brew install $BREW_ALL +$REQUIRE_ANDROID && brew install $BREW_ANDROID +$REQUIRE_IOS && brew install $BREW_IOS +$REQUIRE_WEB && brew install $BREW_WEB +$REQUIRE_MACOS && brew install $BREW_MACOS + +$REQUIRE_PANDOC && brew install pandoc +$REQUIRE_SENTRYCLI && brew install getsentry/tools/sentry-cli + +# Install WINE +$REQUIRE_KMCOMP && ( + brew tap homebrew/cask-versions + brew install --cask --no-quarantine wine-stable +) + +$REQUIRE_WEB && ( + rustup-init -y -t wasm32-unknown-unknown +) + +source "$THIS_DIR/keyman.macos.env.sh" + +$REQUIRE_ANDROID && ( + mkdir -p .android && touch ~/.android/repositories.cfg + + which sdkmanager || ( + echo "Please run Android Studio to install the Android SDK tools." + read -p "Press ENTER to continue after installation" + PATH="$HOME/Library/Android/sdk/tools/bin:$PATH" + ) + sdkmanager "system-images;android-30;google_apis_playstore;x86_64" + sdkmanager --update + sdkmanager --licenses +) + +# For now, we won't run this step automatically +# as it may interfere with other dev environments +#($REQUIRE_IOS || $REQUIRE_MACOS) && ( +# # Assumes that xcode is installed into normal path +# # as otherwise we get only the command line tools which +# # won't build with xcode +# echo "Selecting default xcodebuild command line tools from /Applications/Xcode.app" +# sudo xcode-select -s /Applications/Xcode.app +#) + +# Add keyman.macos.env.sh to ~/.bashrc + +echo "Adding environment variables to ~/.bashrc..." +if [ ! -f ~/.bashrc ] || `grep "keyman.macos.env.sh" ~/.bashrc 2>/dev/null`; then + echo "source $THIS_DIR/keyman.macos.env.sh" >> ~/.bashrc +fi + +echo "Configuration has completed successfully." +echo + +if $REQUIRE_MACOS || $REQUIRE_IOS; then + echo "The following components must be installed manually:" + echo " * XCode" + echo +fi + +if $REQUIRE_MACOS || $REQUIRE_IOS || $REQUIRE_ANDROID; then + echo "The following components should be started manually after this script completes, in order to install" + echo "additional components:" + if $REQUIRE_MACOS || $REQUIRE_IOS; then + echo " * XCode" + echo "You may need to run xcode-select to choose the correct version of XCode command line tools." + fi + if $REQUIRE_ANDROID; then + echo " * Android Studio" + fi + echo +fi diff --git a/web/README.md b/web/README.md index 01d6a5da41..c46288d05c 100644 --- a/web/README.md +++ b/web/README.md @@ -1,20 +1,8 @@ # Keyman Web -The Original Code is (C) 2017-2018 SIL International +The Original Code is (C) SIL International -## Minimum Web Compilation Requirements - -* [Java 7+](https://adoptopenjdk.net/releases.html) (required by the Google Closure Compiler) - * This can be ignored for Keyman Developer builds. -* A local installation of [Node.js](https://nodejs.org/) v8.9+. - * Builds will call `npm install` to automatically install further necessary build dependencies. - - * Linux users can run the following to update to LTS version of nodejs - -``` -sudo apt-get install python-software-properties -curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash - -sudo apt-get install nodejs -``` +## Prerequisites +See [build configuration](../docs/build/index.md) for details on how to configure your build environment. **********************************************************************