spiegel-keyman/docs/build/windows.md

# Setup your Keyman build environment on Windows

## Target Projects

On Windows, you can build the following projects:

* [Keyman for Android](#keyman-for-android)
* [Keyman for Windows](#keyman-for-windows)
* [Keyman Developer](#keyman-developer)
* [KeymanWeb](#keymanweb)

The following libraries can also be built:

* Keyman Core (Windows, wasm targets)
* Common libraries

The following projects **cannot** be built on Windows:

* Keyman for Linux
* Keyman for macOS
* Keyman for iOS

## System Requirements

* Minimum Windows version: Windows 10 x64

## Repository Paths

When cloning this repo for local development on a Windows machine, take care not
to place it overly deep in your file system. Some of the paths for compilation
can push character lengths around 160 characters long, while certain operations
on Windows systems may be limited to paths of 260 characters or less. For
example, [`git clean` on Windows with
msys](https://stackoverflow.com/questions/22575662/filename-too-long-in-git-for-windows/22575737#22575737)
is limited due to dependence on older Windows APIs.

Recommended filesystem layout:

```
C:\Projects\keyman\
  keyman\              this repository (https://github.com/keymanapp/keyman)
  keyboards\           https://github.com/keymanapp/keyboards
  lexical-models\      https://github.com/keymanapp/lexical-models
  CEF4Delphi_Binary\   https://github.com/keymanapp/CEF4Delphi_Binary
  sites\
    keyman.com\        https://github.com/keymanapp/keyman.com
    ...
```

Instructions and scripts in this file assume this layout; if you use a different
layout, adjust the paths accordingly.

We recommend adding an exclusion for C:\Projects to your antivirus/security
software, for performance reasons; this can also avoid build failures when
security software locks generated executables to scan them, before the build has
finished with them.

## Project Requirements

### Keyman for Windows

Dependencies:
* [Base](#base-dependencies)
* [Windows Platform](#windows-platform-dependencies)

Building:
* [Building Keyman for Windows](../../windows/src/README.md)

### Keyman Developer

Dependencies:
* [Base](#base-dependencies)
* [Web](#web-dependencies)
* [Windows Platform](#windows-platform-dependencies) (optional, for Windows-only components)

Building:
* [Building Keyman Developer](../../windows/src/README.md)

### KeymanWeb

Dependencies:
* [Base](#base-dependencies)
* [Web](#web-dependencies)

Building:
* [Building KeymanWeb](../../web/README.md)

### Keyman for Android

**Dependencies**:
* [Base](#base-dependencies)
* [Web](#web-dependencies)
* [Android](#android-dependencies)

Building:
* [Building Keyman for Android](../../android/README.md)

---

## Dependencies and Prerequisites

Many dependencies are only required for specific projects.

We prefer [Chocolatey](https://chocolatey.org/install) at present for
installation of most dependencies. Chocolatey should be run in an elevated
PowerShell.

### Base Dependencies

**Projects**:
* all projects

**Requirements**:
* git for Windows
* jq
* Python 3
* Meson 1.0+
* Ninja
* Pandoc

```ps1
# Elevated PowerShell
# for *much* faster download, hide progress bar (PowerShell/PowerShell#2138)
$ProgressPreference = 'SilentlyContinue'
choco install git jq python ninja pandoc meson
```

**Environment variables**:

If you pull the entire `keyman.git` repo to `c:\keyman`, then the paths by
default will work without changes. Otherwise, you will need to set an
environment variable `KEYMAN_ROOT` to the root path of the Keyman repo. For
example:

```bat
SETX KEYMAN_ROOT "c:\Projects\keyman\keyman"
```

> [!NOTE]
> The `SETX` command will set persistent environment variables but they do not
> impact the current shell environment. Start a new shell to see the variables.

> [!TIP]
>
> To check whether environment variables are set, run `SET <variable>` in command
> prompt.
>
> You can alternatively use Windows Settings to add these environment variables
> permanently:
>
> 1. In Windows Search, type "environment" and select "Edit System Environment
>    Variables"
> 2. Click `Environment Variables...`
> 3. You can add or edit variables in either User or System settings, as you
>    prefer.

### Web Dependencies

**Projects**:
* Keyman Developer
* Keyman for Android
* KeymanWeb

**Requirements**:
* node.js
* Emscripten

#### node.js

Our recommended way to install node.js is to use
[nvm-windows](https://github.com/coreybutler/nvm-windows). This makes it
easy to switch between versions of node.js.

```bat
nvm install 20.16.0
nvm use 20.16.0
```

#### Emscripten

In bash, run the following commands:

```bash
cd /c/Projects/keyman
git clone https://github.com/emscripten-core/emsdk
cd emsdk
emsdk install 3.1.58
emsdk activate 3.1.58
cd upstream/emscripten
npm install
```

If you are updating an existing install of Emscripten:

```bash
cd emsdk
git pull
emsdk install 3.1.58
emsdk activate 3.1.58
cd upstream/emscripten
npm install
```

> ![WARNING]
> Emscripten very unhelpfully overwrites `JAVA_HOME`, and adds its own
> versions of Python, Node and Java to the `PATH`. For best results, restart
> your shell after installing Emscripten so that you don't end up with the
> wrong versions.

There is no need to add emscripten to the path in order to build Keyman.
However, you should set the `EMSCRIPTEN_BASE` variable to the path where `emcc`
can be found, in the `upstream\emscripten` subdirectory of where you installed
emsdk.

**Environment variables**:

```bat
SETX EMSCRIPTEN_BASE "<your-emsdk-path>\upstream\emscripten"
```

**Optional environment variables**:

To let the Keyman build scripts control the version of Emscripten
installed on your computer:

```bat
SETX KEYMAN_USE_EMSDK 1
```

**Optional environment variables**:

To let the Keyman build scripts control the version of node.js installed
and active on your computer:

```bat
SETX KEYMAN_USE_NVM 1
````

See [node.md](node.md) for more information, including automatic selection
of appropriate node versions during builds.

### Windows Platform Dependencies

**Projects**:
* Keyman Developer
* Keyman for Windows

**Requirements**:
* Delphi 10.3 Community or Professional:
  https://www.embarcadero.com/products/delphi/starter/free-download (Delphi
  Windows Community, DUnit Unit Testing Frameworks required)

  * Note: Delphi 10.3 Community is no longer available. Delphi 10.4 Community no
    longer includes command line compilers. This change means that building
    Keyman with Delphi 10.4 Community is not really viable. This means you can
    only really use the Professional Edition, which can be used on a trial basis
    for a short time. (We are actively working to remove Delphi dependencies
    given the licensing issues with using it.)

  Start Delphi IDE once after installation as it will create various environment
  files and take you through required registration.

  * Note: It is possible to build all components that do _not_ require Delphi.
    Currently many components are Delphi-based, but if you are working just in
    Keyman Core, the compiler, or Keyman Engine's C++ components, you may be
    able to get away without building them. In this situation, we recommend
    copying the relevant Delphi-built components into windows/bin folders from a
    compatible installed version of Keyman for testing and debugging purposes.

* Visual Studio 2022 Community (C++ native desktop workload)

  ```cmd
  winget install --id=Microsoft.VisualStudio.2022.Community -e --override "--passive --add Microsoft.VisualStudio.Workload.NativeDesktop --add Microsoft.VisualStudio.Component.VC.Tools.ARM64 --add Microsoft.VisualStudio.Component.CppBuildInsights --add Microsoft.VisualStudio.Component.Debugger.JustInTime --add Microsoft.VisualStudio.Component.VC.ASAN --add Microsoft.VisualStudio.Component.VC.DiagnosticTools --add Microsoft.VisualStudio.Component.VC.TestAdapterForGoogleTest --add Microsoft.VisualStudio.Component.VC.Tools.x86.x64 --add Microsoft.VisualStudio.Component.Windows11SDK.26100 --add Microsoft.VisualStudio.Component.Windows11Sdk.WindowsPerformanceToolkit --add Microsoft.VisualStudio.Component.Windows10SDK.19041"
  ```

  * You can omit the `--passive` parameter to open the installer dialog and
    modify the selection before continuing with the install.

  * You can replace `--passive` with `--quiet` for a silent install (note that
    the winget command returns before the Visual Studio Installer finishes, so
    you won't be able to easily tell when installation completes; check Task
    Manager for setup.exe).

  * If you prefer to use the Visual Studio Installer instead of the command
    line install, then the following workloads and components should be included:
    * Visual Studio core editor
    * Desktop development with C++
      - C++ core desktop features
      - MSVC v143 - VS 2022 C++ x64/x86 build tools (latest)
      - C++ Build Insights
      - Just-In-Time debugger
      - C++ profiling tools
      - Test Adapter for Google Test
      - C++ AddressSanitizer
      - Windows 10 SDK (10.0.19041.0)
      - Windows 11 SDK (10.0.26100.6584)
    * Under individual components, add:
      - MSVC v143 - VS 2022 C++ ARM64/ARM64EC build tools (latest)

  Recommended: configure Visual Studio to use two-space tab stops:
  1. Open the options dialog: Tools > Options.
  2. Navigate to Text Editor > All Languages > Tabs.
  3. Change 'Tab size' to 2 and 'Indent size' to 2.
  4. Select 'Insert spaces'.

* Windows SDK (C++ Desktop Development)

  This should be installed as a part of Visual Studio above

**Required environment variables**:
* `PATH`
  * Add the `C:\Projects\keyman\keyman\windows\lib` folder in the Keyman
    repository to your `PATH` environment variable. This is required for
    Keyman's design-time packages to load in Delphi.

### KEYMAN_CEF4DELPHI_ROOT

Keyman and Keyman Developer use Chromium Embedded Framework. The source repo is
at https://github.com/keymanapp/CEF4Delphi. In order to build the installers, we
need to source the binary files from the
https://github.com/keymanapp/CEF4Delphi_binary repo. The
`KEYMAN_CEF4DELPHI_ROOT` environment variable should be set to the root of this
repo on your local machine.

The version of CEF in use is determined by CEF_VERSION.md. This maps to a branch
prefixed with `v` e.g. `v89.0.18` in the CEF4Delphi_binary repository. During a
release build, the common/windows/cef-checkout.sh script will checkout the correct
branch of the repository automatically and extract any compressed files found in
it.

The [`KEYMAN_CEF4DELPHI_ROOT`](#keyman_cef4delphi_root) variable is
used to specify the path to the CEF4Delphi binaries.

```bat
SETX KEYMAN_CEF4DELPHI_ROOT "c:\Projects\keyman\CEF4Delphi_Binary"
```

**Additional requirements for release builds**:
* [Certificates](#certificates)
* [7-Zip](http://www.7-zip.org/), used for archiving build files
* [HTML Help Workshop](http://web.archive.org/web/20160201063255/http://download.microsoft.com/download/0/A/9/0A939EF6-E31C-430F-A3DF-DFAE7960D564/htmlhelp.exe) note: Microsoft no longer offer this download...
* [WiX 3.11.1](https://github.com/wixtoolset/wix3/releases/tag/wix3111rtm)
* [CEF4Delphi_Binary](https://github.com/keymanapp/CEF4Delphi_Binary) repository

```ps1
# Elevated PowerShell
choco install 7zip html-help-workshop
choco install wixtoolset --version=3.14.1
git clone https://github.com/keymanapp/CEF4Delphi_Binary C:\Projects\keyman\CEF4Delphi_Binary
```

### Android dependencies

**Projects**:
* Keyman for Android

**Requirements**:
* Android SDK
* Android Studio
* Ant
* Gradle
* Maven
* JDK 11 (Temurin11)

#### JDK 11

Use Powershell + Chocolatey to install JDK 11:

```ps1
# Elevated PowerShell

# for *much* faster download, hide progress bar (PowerShell/PowerShell#2138)
$ProgressPreference = 'SilentlyContinue'
choco install temurin11
```

**Multiple versions of Java:** If you need to build Keyman for Android 16.0 or
older versions, you can set `JAVA_HOME_11` to the JDK 11 path and
`JAVA_HOME` to the JDK 8 path. This will build both versions correctly
from command line. But note that you do need to update your `JAVA_HOME` env
var to the associated version before opening Android Studio and loading any
Android projects. `JAVA_HOME_11` is mostly used by CI.

#### Android Studio and friends

```ps1
# Elevated PowerShell
choco install androidstudio ant gradle maven android-sdk
```

Start a new shell to get the new paths and then update Android SDKs:

```ps1
# optionally install sdk images
sdkmanager --update
# sdkmanager "system-images;android-33;google_apis;armeabi-v7a"
sdkmanager --licenses
```

* Run Android Studio once after installation to install additional components
  such as emulator images and SDK updates.

## Certificates

In order to make a release build, you need to sign all the executables. See
[windows/src/README.md#Certificates](../../windows/src/README.md#Certificates)
for details on how to create test code signing certificates or specify your own
certificates for the build.

## Optional Tools

* sentry-cli (optional)
  - Uploading symbols for Sentry-based error reporting

  bash:
  ```bash
  # bash
  curl -sL https://sentry.io/get-cli/ | bash
  ```