From 4af39a58b0e424f11cab7438280fb20754cf7b3c Mon Sep 17 00:00:00 2001 From: Marc Durdin Date: Mon, 21 Jun 2021 21:12:27 +1000 Subject: [PATCH 1/4] docs: start consolidation of build config docs As the build environment documentation is duplicated across each of the Keyman platform projects, it has become somewhat convoluted and inconsistent. This PR moves all the mac-based and shared documentation into docs/build, with placeholders for Windows and Linux documentation to be moved in the next PR. The idea is that a developer can configure their box to build any of the available projects for that platform (web and android build on all three main dev platforms). Keeping the build documentation in one place makes it much simpler to keep it consistent and up-to-date as well, as well as keeping us aware of potential dependency conflicts between projects. The icing on the cake is the resources/devbox/macos/macos.sh script, which I have tested and takes a bare metal mac box through to a full Keyman development environment (except XCode, there's always something!) --- android/README.md | 62 +----- common/core/desktop/doc/BUILDING.md | 227 +------------------- docs/build/android-notes.md | 51 +++++ docs/build/core-desktop-notes.md | 229 +++++++++++++++++++++ docs/build/index.md | 25 +++ docs/build/ios-notes.md | 19 ++ docs/build/linux-ubuntu.md | 3 + docs/build/macos-notes.md | 15 ++ docs/build/macos.md | 101 +++++++++ docs/build/sentry-cli-notes.md | 14 ++ docs/build/web-notes.md | 16 ++ docs/build/windows.md | 3 + ios/README.md | 26 +-- mac/README.md | 13 -- resources/devbox/macos/keyman.macos.env.sh | 19 ++ resources/devbox/macos/macos.sh | 149 ++++++++++++++ web/README.md | 18 +- 17 files changed, 651 insertions(+), 339 deletions(-) create mode 100644 docs/build/android-notes.md create mode 100644 docs/build/core-desktop-notes.md create mode 100644 docs/build/index.md create mode 100644 docs/build/ios-notes.md create mode 100644 docs/build/linux-ubuntu.md create mode 100644 docs/build/macos-notes.md create mode 100644 docs/build/macos.md create mode 100644 docs/build/sentry-cli-notes.md create mode 100644 docs/build/web-notes.md create mode 100644 docs/build/windows.md create mode 100644 resources/devbox/macos/keyman.macos.env.sh create mode 100755 resources/devbox/macos/macos.sh 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/android-notes.md b/docs/build/android-notes.md new file mode 100644 index 0000000000..b3e0dd8ad3 --- /dev/null +++ b/docs/build/android-notes.md @@ -0,0 +1,51 @@ +# Keyman for Android configuration notes + +* 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 + +## 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/core-desktop-notes.md b/docs/build/core-desktop-notes.md new file mode 100644 index 0000000000..dc5f6ea9f9 --- /dev/null +++ b/docs/build/core-desktop-notes.md @@ -0,0 +1,229 @@ +# Common/Core/Desktop configuration notes + +- 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/index.md b/docs/build/index.md new file mode 100644 index 0000000000..6362c38739 --- /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](building-linux-ubuntu.md) +* [macOS](building-macos.md) +* [Windows](building-windows.md) + +## Additional Configuration Documentation + +Additional notes are available in the following documents: + +* [sentry-cli notes](sentry-cli-notes.md) + +Older notes: + +* [Keyman for Android notes](android-notes.md) +* [Keyman for iOS notes](ios-notes.md) +* [Keyman for macOS notes](macos-notes.md) +* [KeymanWeb notes](web-notes.md) +* [Keyman Core Desktop notes](core-desktop.md) + +Many folders may also contain other build instructions in README.md files. diff --git a/docs/build/ios-notes.md b/docs/build/ios-notes.md new file mode 100644 index 0000000000..33f772b624 --- /dev/null +++ b/docs/build/ios-notes.md @@ -0,0 +1,19 @@ +# Keyman for iOS configuration notes + +## 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/linux-ubuntu.md b/docs/build/linux-ubuntu.md new file mode 100644 index 0000000000..2c9da3268c --- /dev/null +++ b/docs/build/linux-ubuntu.md @@ -0,0 +1,3 @@ +## Setup your Keyman build environment on Ubuntu + +TODO \ No newline at end of file diff --git a/docs/build/macos-notes.md b/docs/build/macos-notes.md new file mode 100644 index 0000000000..234e5be167 --- /dev/null +++ b/docs/build/macos-notes.md @@ -0,0 +1,15 @@ +# Keyman for macOS configuration notes + +## 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/macos.md b/docs/build/macos.md new file mode 100644 index 0000000000..e720b7f202 --- /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 this 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 + + ```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 + brew install rustup-init + ``` + +* Web: node.js, emscripten, wasm-pack + + ```shell + brew install node emscripten wasm-pack + 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, Pandoc + + ```shell + brew install openjdk@8 android-sdk android-studio ant gradle maven pandoc + # 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 diff --git a/docs/build/sentry-cli-notes.md b/docs/build/sentry-cli-notes.md new file mode 100644 index 0000000000..e312a5e603 --- /dev/null +++ b/docs/build/sentry-cli-notes.md @@ -0,0 +1,14 @@ +#### 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`. diff --git a/docs/build/web-notes.md b/docs/build/web-notes.md new file mode 100644 index 0000000000..0dbc0d06ee --- /dev/null +++ b/docs/build/web-notes.md @@ -0,0 +1,16 @@ +# KeymanWeb configuration notes + +## 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/windows.md b/docs/build/windows.md new file mode 100644 index 0000000000..81fc537eae --- /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..b15a3be708 --- /dev/null +++ b/resources/devbox/macos/macos.sh @@ -0,0 +1,149 @@ +#!/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 + +while [[ $# -gt 0 ]] ; do + key="$1" + case $key in + --help) + echo "Usage: macos.sh targets" + echo " targets: one or more of: " + echo " android ios macos web all" + echo " optional targets:" + echo " kmcomp pandoc sentry-cli" + ;; + android) + $REQUIRE_ANDROID=true + ;; + ios) + $REQUIRE_IOS=true + ;; + macos) + $REQUIRE_MACOS=true + ;; + web) + $REQUIRE_WEB=true + ;; + kmcomp) + $REQUIRE_KMCOMP=true + ;; + pandoc) + $REQUIRE_PANDOC=true + ;; + sentry-cli) + $REQUIRE_SENTRYCLI=true + ;; + all) + REQUIRE_ANDROID=true + REQUIRE_IOS=true + REQUIRE_MACOS=true + REQUIRE_WEB=true + ;; + *) + echo "Error: unrecognised parameter. Use --help for help" + ;; + esac + shift +done + +# 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 building.md." +read -p "Press ENTER to start install" + +if $REQUIRE_IOS || $REQUIRE_ANDROID; then + REQUIRE_WEB=true +fi + +if $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" +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 +) + +($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 + sudo xcode-select -s /Applications/Xcode.app +) + +# Add macos.env.sh 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 + 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. ********************************************************************** From c6e6c2a225dc348a0c76994ed7c8ec58304d64f1 Mon Sep 17 00:00:00 2001 From: Marc Durdin Date: Tue, 22 Jun 2021 16:11:53 +1000 Subject: [PATCH 2/4] chore: Apply suggestions from code review Co-authored-by: Eberhard Beilharz --- docs/build/index.md | 8 ++++---- docs/build/linux-ubuntu.md | 4 ++-- docs/build/macos.md | 20 ++++++++++---------- docs/build/sentry-cli-notes.md | 2 +- docs/build/windows.md | 2 +- 5 files changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/build/index.md b/docs/build/index.md index 6362c38739..c001d6a8f9 100644 --- a/docs/build/index.md +++ b/docs/build/index.md @@ -4,9 +4,9 @@ Keyman has a wide range of dependencies. We are working to reduce the complexity ## Development Platforms -* [Linux - Ubuntu](building-linux-ubuntu.md) -* [macOS](building-macos.md) -* [Windows](building-windows.md) +* [Linux - Ubuntu](linux-ubuntu.md) +* [macOS](macos.md) +* [Windows](windows.md) ## Additional Configuration Documentation @@ -20,6 +20,6 @@ Older notes: * [Keyman for iOS notes](ios-notes.md) * [Keyman for macOS notes](macos-notes.md) * [KeymanWeb notes](web-notes.md) -* [Keyman Core Desktop notes](core-desktop.md) +* [Keyman Core Desktop notes](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 index 2c9da3268c..910a3b8d2d 100644 --- a/docs/build/linux-ubuntu.md +++ b/docs/build/linux-ubuntu.md @@ -1,3 +1,3 @@ -## Setup your Keyman build environment on Ubuntu +# Setup your Keyman build environment on Ubuntu -TODO \ No newline at end of file +TODO diff --git a/docs/build/macos.md b/docs/build/macos.md index e720b7f202..db914ad5aa 100644 --- a/docs/build/macos.md +++ b/docs/build/macos.md @@ -1,6 +1,6 @@ -## Setup your Keyman build environment on macOS +# Setup your Keyman build environment on macOS -### Target Projects +## Target Projects On macOS, you can build the following projects: @@ -12,19 +12,19 @@ On macOS, you can build the following projects: The following libraries can also be built: * Common/Core/Desktop (macOS, wasm targets) -* Common/Core/Web +* Common/Core/Web -The following projects cannot be built on macOS: +The following projects **cannot** be built on macOS: * Keyman for Linux * Keyman for Windows * Keyman Developer -### System Requirements +## System Requirements * Minimum macOS version: macOS Catalina 10.15 or Big Sur 11.0 -### Prerequisites +## Prerequisites Many dependencies are only required for specific projects. @@ -38,11 +38,11 @@ The remaining dependencies can be installed via script: This script will also update your environment to the values in: `resources/devbox/macos/keyman.macos.env.sh` -It will also add this to your `~/.bashrc`. +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 Dependencies * Shared: HomeBrew, Bash 5.0+, jq, Python 3, Meson, Ninja, Rust, coreutils @@ -52,10 +52,10 @@ These dependencies are also listed below if you'd prefer to install manually. brew install rustup-init ``` -* Web: node.js, emscripten, wasm-pack +* Web: node.js, emscripten, wasm-pack, openjdk 8 ```shell - brew install node emscripten wasm-pack + brew install node emscripten wasm-pack openjdk@8 rustup target add wasm32-unknown-unknown ``` diff --git a/docs/build/sentry-cli-notes.md b/docs/build/sentry-cli-notes.md index e312a5e603..968c42e3ae 100644 --- a/docs/build/sentry-cli-notes.md +++ b/docs/build/sentry-cli-notes.md @@ -1,4 +1,4 @@ -#### Setting up sentry-cli +# 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. diff --git a/docs/build/windows.md b/docs/build/windows.md index 81fc537eae..f0f48e0733 100644 --- a/docs/build/windows.md +++ b/docs/build/windows.md @@ -1,3 +1,3 @@ -## Setup your Keyman build environment on Windows +# Setup your Keyman build environment on Windows TODO From 4e878664d41488471a98e36b76499c5df6afe96f Mon Sep 17 00:00:00 2001 From: Marc Durdin Date: Wed, 23 Jun 2021 06:15:53 +1000 Subject: [PATCH 3/4] docs: address review comments * Move old notes into an old/ folder to clarify their pending removal and add a note to the top of each file. * Cleanup macos.sh script to fix various issues. --- docs/build/index.md | 12 +-- docs/build/{ => old}/android-notes.md | 4 +- docs/build/{ => old}/core-desktop-notes.md | 2 + docs/build/{ => old}/ios-notes.md | 2 + docs/build/{ => old}/macos-notes.md | 2 + docs/build/{ => old}/web-notes.md | 2 + .../{sentry-cli-notes.md => sentry-cli.md} | 0 resources/devbox/macos/macos.sh | 93 ++++++++++++++----- 8 files changed, 89 insertions(+), 28 deletions(-) rename docs/build/{ => old}/android-notes.md (95%) rename docs/build/{ => old}/core-desktop-notes.md (98%) rename docs/build/{ => old}/ios-notes.md (91%) rename docs/build/{ => old}/macos-notes.md (86%) rename docs/build/{ => old}/web-notes.md (86%) rename docs/build/{sentry-cli-notes.md => sentry-cli.md} (100%) diff --git a/docs/build/index.md b/docs/build/index.md index c001d6a8f9..bca0627234 100644 --- a/docs/build/index.md +++ b/docs/build/index.md @@ -12,14 +12,14 @@ Keyman has a wide range of dependencies. We are working to reduce the complexity Additional notes are available in the following documents: -* [sentry-cli notes](sentry-cli-notes.md) +* [sentry-cli configuration](sentry-cli.md) Older notes: -* [Keyman for Android notes](android-notes.md) -* [Keyman for iOS notes](ios-notes.md) -* [Keyman for macOS notes](macos-notes.md) -* [KeymanWeb notes](web-notes.md) -* [Keyman Core Desktop notes](core-desktop-notes.md) +* [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/android-notes.md b/docs/build/old/android-notes.md similarity index 95% rename from docs/build/android-notes.md rename to docs/build/old/android-notes.md index b3e0dd8ad3..512044b881 100644 --- a/docs/build/android-notes.md +++ b/docs/build/old/android-notes.md @@ -1,7 +1,9 @@ # 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 +* Java SE Development Kit 8 * [Node.js](https://nodejs.org/) 14.17+ (for building KeymanWeb) * [Pandoc](#Install-Pandoc) for generating offline help diff --git a/docs/build/core-desktop-notes.md b/docs/build/old/core-desktop-notes.md similarity index 98% rename from docs/build/core-desktop-notes.md rename to docs/build/old/core-desktop-notes.md index dc5f6ea9f9..4eceb94fd0 100644 --- a/docs/build/core-desktop-notes.md +++ b/docs/build/old/core-desktop-notes.md @@ -1,5 +1,7 @@ # 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) diff --git a/docs/build/ios-notes.md b/docs/build/old/ios-notes.md similarity index 91% rename from docs/build/ios-notes.md rename to docs/build/old/ios-notes.md index 33f772b624..47fd967f0e 100644 --- a/docs/build/ios-notes.md +++ b/docs/build/old/ios-notes.md @@ -1,5 +1,7 @@ # Keyman for iOS configuration notes +WARNING: these are old configuration notes. See [macos.md](../macos.md) for current steps. + ## Prerequisites * Xcode 11 * iOS 9+ diff --git a/docs/build/macos-notes.md b/docs/build/old/macos-notes.md similarity index 86% rename from docs/build/macos-notes.md rename to docs/build/old/macos-notes.md index 234e5be167..77a83bd038 100644 --- a/docs/build/macos-notes.md +++ b/docs/build/old/macos-notes.md @@ -1,5 +1,7 @@ # 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* diff --git a/docs/build/web-notes.md b/docs/build/old/web-notes.md similarity index 86% rename from docs/build/web-notes.md rename to docs/build/old/web-notes.md index 0dbc0d06ee..23ebf26d61 100644 --- a/docs/build/web-notes.md +++ b/docs/build/old/web-notes.md @@ -1,5 +1,7 @@ # 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) diff --git a/docs/build/sentry-cli-notes.md b/docs/build/sentry-cli.md similarity index 100% rename from docs/build/sentry-cli-notes.md rename to docs/build/sentry-cli.md diff --git a/resources/devbox/macos/macos.sh b/resources/devbox/macos/macos.sh index b15a3be708..0ddc488443 100755 --- a/resources/devbox/macos/macos.sh +++ b/resources/devbox/macos/macos.sh @@ -22,54 +22,81 @@ REQUIRE_SENTRYCLI=false # Parse args shopt -s nocasematch +PARAMFOUND=false + +function print_help() { + echo "Usage: macos.sh targets" + echo " targets: one or more of: " + echo " android ios macos web all" + echo " optional targets:" + echo " kmcomp pandoc sentry-cli" + echo "Targets will automatically include dependency targets." +} + while [[ $# -gt 0 ]] ; do key="$1" case $key in --help) - echo "Usage: macos.sh targets" - echo " targets: one or more of: " - echo " android ios macos web all" - echo " optional targets:" - echo " kmcomp pandoc sentry-cli" + print_help + exit 0 ;; android) - $REQUIRE_ANDROID=true + REQUIRE_ANDROID=true + PARAMFOUND=true ;; ios) - $REQUIRE_IOS=true + REQUIRE_IOS=true + PARAMFOUND=true ;; macos) - $REQUIRE_MACOS=true + REQUIRE_MACOS=true + PARAMFOUND=true ;; web) - $REQUIRE_WEB=true + REQUIRE_WEB=true + PARAMFOUND=true ;; kmcomp) - $REQUIRE_KMCOMP=true + REQUIRE_KMCOMP=true + PARAMFOUND=true ;; pandoc) - $REQUIRE_PANDOC=true + REQUIRE_PANDOC=true + PARAMFOUND=true ;; sentry-cli) - $REQUIRE_SENTRYCLI=true + REQUIRE_SENTRYCLI=true + PARAMFOUND=true ;; all) REQUIRE_ANDROID=true REQUIRE_IOS=true REQUIRE_MACOS=true REQUIRE_WEB=true + PARAMFOUND=true ;; *) - echo "Error: unrecognised parameter. Use --help for help" + echo "Error: unrecognised parameter." + echo + print_help + exit 1 ;; esac shift done +if ! $PARAMFOUND; then + echo "Error: must have a 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 building.md." +echo read -p "Press ENTER to start install" if $REQUIRE_IOS || $REQUIRE_ANDROID; then @@ -95,7 +122,7 @@ which brew || ( ## Install devchain components BREW_ALL="bash jq python3 meson ninja rustup-init coreutils" -BREW_WEB="node emscripten wasm-pack" +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" @@ -134,16 +161,40 @@ $REQUIRE_ANDROID && ( sdkmanager --licenses ) -($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 - sudo xcode-select -s /Applications/Xcode.app -) +# 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 macos.env.sh to ~/.bashrc +# 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" + fi + if $REQUIRE_ANDROID; then + echo " * Android Studio" + fi + echo +fi From 2034818485d56ea2535ecc640c0fd499a985239e Mon Sep 17 00:00:00 2001 From: Marc Durdin Date: Wed, 30 Jun 2021 13:03:30 +1000 Subject: [PATCH 4/4] chore: address review comments --- docs/build/macos.md | 16 +++++++------- docs/build/old/android-notes.md | 9 +++++--- docs/build/sentry-cli.md | 7 +++--- resources/devbox/macos/macos.sh | 38 +++++++++++++++++++++++++++------ 4 files changed, 49 insertions(+), 21 deletions(-) diff --git a/docs/build/macos.md b/docs/build/macos.md index db914ad5aa..41a45f7ad2 100644 --- a/docs/build/macos.md +++ b/docs/build/macos.md @@ -34,22 +34,21 @@ Many dependencies are only required for specific projects. 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 +* 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 - brew install rustup-init + brew install bash jq python3 meson ninja rustup-init coreutils pandoc rustup-init ``` * Web: node.js, emscripten, wasm-pack, openjdk 8 @@ -60,7 +59,7 @@ These dependencies are also listed below if you'd prefer to install manually. ``` * iOS: swiftlint, carthage - + ```shell brew install swiftlint carthage ``` @@ -71,10 +70,10 @@ These dependencies are also listed below if you'd prefer to install manually. brew install carthage cocoapods ``` -* Android: openjdk 8, Android SDK, Android Studio, Ant, Gradle, Maven, Pandoc +* Android: openjdk 8, Android SDK, Android Studio, Ant, Gradle, Maven ```shell - brew install openjdk@8 android-sdk android-studio ant gradle maven pandoc + 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 @@ -99,3 +98,4 @@ These dependencies are also listed below if you'd prefer to install manually. ``` * 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 index 512044b881..409f0057b2 100644 --- a/docs/build/old/android-notes.md +++ b/docs/build/old/android-notes.md @@ -8,13 +8,13 @@ WARNING: these are old configuration notes. See [index.md](../index.md) for curr * [Pandoc](#Install-Pandoc) for generating offline help ## Install Java -It is recommended to use openJDK because of oracle license issues. +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 +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 @@ -22,16 +22,19 @@ https://github.com/ojdkbuild/ojdkbuild 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 ``` diff --git a/docs/build/sentry-cli.md b/docs/build/sentry-cli.md index 968c42e3ae..7136bee2c1 100644 --- a/docs/build/sentry-cli.md +++ b/docs/build/sentry-cli.md @@ -1,14 +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. +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, from the `android/` folder run `sentry-cli info`. +To validate your configuration, for example for keyman-android, from the `android/` folder run `sentry-cli info`. diff --git a/resources/devbox/macos/macos.sh b/resources/devbox/macos/macos.sh index 0ddc488443..a5e7232e46 100755 --- a/resources/devbox/macos/macos.sh +++ b/resources/devbox/macos/macos.sh @@ -26,11 +26,24 @@ PARAMFOUND=false function print_help() { echo "Usage: macos.sh targets" - echo " targets: one or more of: " - echo " android ios macos web all" + 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 pandoc sentry-cli" - echo "Targets will automatically include dependency 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 @@ -75,6 +88,16 @@ while [[ $# -gt 0 ]] ; do 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 @@ -86,7 +109,7 @@ while [[ $# -gt 0 ]] ; do done if ! $PARAMFOUND; then - echo "Error: must have a target parameter" + echo "Error: must specify target parameter" echo print_help exit 1 @@ -95,7 +118,7 @@ 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 building.md." +echo "You can also do this yourself following the notes in docs/build/macos.md." echo read -p "Press ENTER to start install" @@ -103,7 +126,7 @@ if $REQUIRE_IOS || $REQUIRE_ANDROID; then REQUIRE_WEB=true fi -if $REQUIRE_ANDROID; then +if $REQUIRE_IOS || $REQUIRE_MACOS || $REQUIRE_ANDROID; then REQUIRE_PANDOC=true fi @@ -192,6 +215,7 @@ if $REQUIRE_MACOS || $REQUIRE_IOS || $REQUIRE_ANDROID; then 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"