# Installation
This chapter covers installing the application and its dependencies, including
the typesetting software required for PDF generation. Generating PDF files
requires the following components:
* {{app.title}} binary
* {{app.title}} theme pack
* ConTeXt typesetting system
The easiest way to get started is to download a {{app.title}} binary for your
operating system, run it, then launch the guided wizard as per [@sec:wizard].
The wizard will download and install all necessary components.
{{app.title}} binaries are self-extracting, except for the Java archive
(`.jar`) version. Installing the Java archive version is useful for platforms
that don't have prebult {{app.title}} binaries. The Java archive version is
described in [@sec:java-runtime-environment].
## Wizard
Launch the wizard as follows:
1. [Download](https://keenwrite.com) {{app.title}}.
1. Start {{app.title}}.
1. Click **File → Export As → PDF**.
The installation wizard installs a container manager and typesetter container
image. The container image is a self-contained operating system that includes
the typesetting software, theme pack, and fonts. Using a container reduces the
number of manual installation steps.
## Java Runtime Environment
Using the Java archive version of {{app.title}} requires the following:
* `{{install.java}}` file.
* Java Runtime Environment (JRE) **{{version.java}}** with JavaFX.
* {{app.title}} launch script.
Software developers may choose to use the Java Development Kit (JDK)
**{{version.java}}**.
### Download {{app.title}}
[Download](https://keenwrite.com/) the Java archive version of {{app.title}}.
### JRE with JavaFX
Install a JRE **{{version.java}}** version that bundles JavaFX.
1. Visit the BellSoft's Liberica JDK [download page](https://bell-sw.com/pages/downloads/#jdk-24).
1. Select the JDK corresponding to **{{version.java}}**.
1. Scroll down to the desired operating system.
1. Optionally, change the target CPU architecture.
1. Set **Package** to: `Full JRE`.
1. Download the `.zip` or `.tar.gz` file.
After downloading the *full* JRE, install it and make sure Java can be found
when run. On Unix systems, my preferred installation method follows:
1. Edit `$HOME/.bashrc`.
1. Add `export JAVA_HOME="/opt/jre"`.
1. Add `export PATH="${PATH}:{{install.path.unix.bin}}:${JAVA_HOME}/bin"`.
1. Save the file.
1. Install into `/opt/jre-{{version.java}}-full` and link to `/opt/jre`:
``` bash
sudo su -
cd /opt
JAVA_DIR="jre-{{version.java}}-full"
mkdir "${JAVA_DIR}"
tar xf bellsoft-jre{{version.java}}-linux-amd64-full.tar.gz \
-C "${JAVA_DIR}" --strip-components=1
ln -sf "${JAVA_DIR}" jre
```
Pointing the symbolic link `/opt/jre` to `/opt/jre-{{version.java}}-full`
enables upgrading the JRE without having to update the `.bashrc` for each
new version.
### Unix launch script
On Unix-based systems (Linux, macOS, FreeBSD, alpine, etc.), install the
launch script as follows:
1. Open a terminal.
1. Download the [launcher script](https://repo.autonoma.ca/?action=raw&repo=keenwrite.git&hash=225340adcfad6aad060a7ddc33b8b36f82472379&name=keenwrite.sh) into `{{install.path.unix.bin}}`.
1. Make the script executable.
1. Download or move the `.jar` file into `{{install.path.unix.bin}}`.
Provided `{{install.path.unix.bin}}` is part of the `PATH` environment
variable, {{app.title}} can be run by typing `{{install.unix.java}}` and
pressing [⏎ Enter]{.kbd}.
### Windows launch script
On Windows-based systems, install the launch script as follows:
1. Create a directory, such as `C:\Program Files\{{app.title}}`.
1. Download the [launcher script](https://repo.autonoma.ca/?action=blob&repo=keenwrite.git&hash=aa29c471c2903f047ef9139b9370282528406fae&name=keenwrite.bat&theme=dark).
1. Rename the file from `.bat.txt` to `.bat`, if necessary.
1. Download or move the `.bat` file into `C:\Program Files\{{app.title}}`.
1. Download or move the `.jar` file into `C:\Program Files\{{app.title}}`.
The Java version of {{app.title}} is installed.
Note: {{app.title}} may be installed in any directory, so if you do not have
permissions to install it under `C:\Program Files\{{app.title}}`, you may opt
for another directory, such as `C:\Users\%USERNAME%\{{app.title}}`.
## ConTeXt LMTX
For users who prefer more control over the installation process, manually
download and configure the typesetting software as follows:
1. Start {{app.title}}.
1. Click **File → Export As → PDF**.
1. Note the following details (e.g., Windows x86 64-bit):
* operating system name;
* instruction set; and
* architecture.
1. Click the [install page](https://wiki.contextgarden.net/Introduction/Installation) link in the dialog.
1. Download the archive file for your operating system and architecture.
Follow the steps that apply to the computer's operating system:
* [Unix](#unix) (includes macOS, FreeBSD, Linux, and similar)
* [Windows](#windows) (includes Windows 7, Windows 10, and similar)
### Unix
On Linux, macOS, FreeBSD, and similar systems, replace `context-linux-64.zip`
with the version appropriate to your operating system and CPU architecture.
Proceed:
1. Open a terminal.
1. Run the following commands:
ConTeXt is installed; jump to [@sec:verification].
### Windows
On a Windows operating system, install the typesetting software as follows:
1. Extract the `.zip` file into `C:\Users\%USERNAME%\AppData\Local\context` (the "root" directory).
1. Run **install.bat** to download and install the software.
* If prompted, click **Run** (or click **More info** first).
1. Download [localpath.bat]({{install.url.windows.path}}).
1. Save the file to the typesetting software's "root" directory.
1. Rename the file from `.bat.txt` to `.bat`, if necessary.
1. Run `localpath.bat` (to set and save the `PATH` environment variable).
ConTeXt is installed.
### Verification
After completing the installation process, verify that the typesetting software
has been installed correctly as follows:
1. Open a new terminal or command prompt.
1. Type: `context --version`
1. Press [⏎ Enter]{.kbd}.
If version information is displayed then the software is installed correctly.
## Theme packs
Theme packs define the visual appearance and styling of typeset documents.
Installing and configuring theme packs is essential for producing high-quality
PDF files. Each theme has its own requirements.
### Install theme pack
Install and configure the theme pack as follows:
1. Download the [theme-pack.zip](https://gitlab.com/DaveJarvis/keenwrite-themes/-/releases/permalink/latest/downloads/theme-pack.zip) archive.
1. Extract the archive.
- On Unix, use `{{install.config.unix}}/`.
- On Windows, use `{{install.config.win}}\`.
1. Start {{app.title}}, if not already running.
1. Click **Edit → Preferences**.
1. Click **Typesetting**.
1. Click **Browse** beside **Themes**.
1. Navigate to the `themes` directory.
- On Unix, `{{install.config.unix}}/themes/`.
- On Windows, `{{install.config.win}}\themes\`.
1. Click **Open**.
1. Click **OK**.
The theme pack is installed.
### Configure theme
Once a theme pack is installed, additional configuration may be required based
on the theme's formatting needs. Configure individual themes based on their
specific requirements. For example, the _Boschet_ theme requires downloading
and installing specific font families, which include:
* [Inconsolata]({{fonts.url}}/inconsolata.zip)
* [Libre Baskerville]({{fonts.url}}/libre-baskerville.zip)
* [Niconne]({{fonts.url}}/niconne.zip)
* [Open Sans Emoji]({{fonts.url}}open-sans-emoji.zip)
* [Source Serif 4]({{fonts.url}}/source-serif-4.zip)
* [TW Kai]({{fonts.url}}/tw-kai.zip)
* [Underwood Quiet Tab]({{fonts.url}}/underwood.zip)
See your operating system instructions for how to install a font.
When running ConTeXt within the typesetter container image, all fonts are
included.
## Run
Running {{app.title}} will depend on the operating system and installation
method. [@tbl:install-app-launchers] lists the executable file name used to
start the application.
| Operating System | Method | Launcher file name |
|------------------|--------------|-----------------|
| Unix | Binary | `{{install.unix.native}}` |
| Unix | Java archive | `{{install.unix.java}}` |
| macOS | Binary | `{{install.mac.native}}` |
| macOS | Java archive | `{{install.mac.java}}` |
| Windows | Binary | `{{install.win.native}}` |
| Windows | Java archive | `{{install.win.java}}` |
:: {{app.title}} launchers {#tbl:install-app-launchers}