@fontoxml/fontoxml-development-tools/README.md

Development tools for Fonto.

# fontoxml-development-tools

The Fonto Development Tools (FDT) are command-line tools that support developers when configuring [Fonto Editor](https://www.fontoxml.com/) and its complementary products, and facilitate running them locally for testing purposes. They act as a gateway to Fonto's SDK and can be used for creating and updating Editor instances, and preparing XML schemas for use with Fonto Editor.

## Installation

### Node

FDT requires [NPM](https://www.npmjs.com/get-npm/) on [Node.js®](https://nodejs.org/) version 20.9 or higher, which are freely available. An active or maintenance LTS release is recommended. After installing Node.js you can continue with installing FDT. There are several options to choose from depending on your use case. Make sure to always install the version of FDT that matches the SDK version you like to use to ensure compatibility between the two.

If you only need to work with a single version of Fonto's SDK then you can install FDT globally on your system. This will make the `fdt` command available in every command-line shell session. Run the following command from anywhere:

    npm install --global @fontoxml/fontoxml-development-tools

Alternatively, if you're maintaining multiple Editor instances that each run on a different SDK version it's best to install FDT locally to your project. Run the following command in your project folder:

    npm install --save-dev --save-prefix=~ @fontoxml/fontoxml-development-tools

After that completes you execute any FDT command using the `npx` utility that's provided by NPM. Run the following command in your project folder:

    npx fdt --version

It's also possible to run an FDT command without (permanently) installing it. This can be useful for e.g. successive upgrades when there's no need to keep the intermediate versions installed. This can be done with the `npx` utility. The following command can be run from anywhere, installs FDT into a temporary cache, and then executes the provided FDT command:

    npx @fontoxml/fontoxml-development-tools@8.3.0 editor upgrade

### Docker

Certain commands, like `fdt review run` and `fdt review build`, require [Docker](https://www.docker.com/) to be installed together with the Docker Compose plugin. Please refer to the [Docker installation instructions](https://docs.docker.com/install/) and the [Compose installation instructions](https://docs.docker.com/compose/install/) to install them.

> The Docker Compose plugin differs from the `docker-compose` standalone tool. Run `docker compose version` to verify its availability. Newer versions of Docker Desktop include the plugin by default.

## Usage

Get help for the available commands:

    fdt --help

Get help for a specific command, detailing all its arguments:

    fdt <command> --help

Output the current FDT version:

    fdt --version

## Development license

Certain commands, like `editor`, `connectors` and `content-quality`, require a valid developer license file on your system and the permissions to run them. A license file `fonto.lic` can be stored in either of these locations:

-   In your user home directory (`$HOME` on linux/MacOS, or `%homepath%` on Windows).
-   In an ancestor folder of where you're running the `fdt` command.

Verify that your license file is installed correctly by running the `fdt license validate` command.

To obtain a license file, or to obtain additional permissions, please contact [Fonto's sales team](https://fontoxml.com/contact/) or reach out to [Fonto's support team](https://support.fontoxml.com/). License files are personal and we strongly advise against storing them in any version control system you might have.

## Proxies

To validate development licenses and access Fonto's services, FDT requires network access. This can be an issue when running FDT on machines that are only allowed to connect through a proxy server. To this end, FDT supports the `HTTP_PROXY` and `HTTPS_PROXY` environment variable convention. These can be set to a valid URI. The `NO_PROXY` environment variable can be set to a comma-separated list of excluded hosts. It supports the following syntax:

-   `.example.com` and `example.com` are equivalent and match _all_ requests to that domain, including subdomains.
-   `example.com:5555` _only_ matches requests to port `5555` on that domain.
-   `*` matches _all_ requests.

## Usage examples

### Licensing

Validate and update the currently installed license file:

    fdt license validate

### Versions

Output the current FDT version:

    fdt version

Output all available SDK versions:

    fdt versions

### Editor

Create a new instance of Fonto Editor:

    fdt editor init [<output>] [--version <version|'nightly'>] [--name <name>] [--schema <path>] [--add-ons <addonName> [<addonName> ...]] [--non-interactive]

Upgrade an instance of Fonto Editor:

    fdt editor upgrade [--version <version|'nightly'>] [--non-interactive]

Add add-ons to, or remove add-ons from, a Fonto Editor instance:

    fdt editor add-ons [--add <addonName> [<addonName> ...]] [--remove <addonName> [<addonName> ...]] [--add-ons <addonName> [<addonName> ...]] [--non-interactive]

Start a development server for running a Fonto Editor instance:

    fdt editor run [--additional-revision-id-on <on> [<on> ...]] [--body-parser-limit <limit>] [--cache-control-disabled] [--cache-control-max-age <maxAge>] [--delay <delay>] [--disable-dist-authentication] [--dist] [--lock-not-acquired] [--lock-not-available] [--memory-store-ttl <seconds>] [--open] [--port] [--release-locks-on-state-request] [--savemode <savemode>] [--verbose]

Create a build version of a Fonto Editor instance for production usage:

    fdt editor build [--no-mangle]

Compile a XSD schema to a schema format which can be used by Fonto Editor:

    fdt editor schema compile [<input>] [--overwrite] [--version <version|'nightly'>]

### Localization

Extract messages from packages and save them in a message bundle template:

    fdt localization extract [<output>] [--paths <package1> [<package2> ...]]

Merge multiple message bundles into a single bundle:

    fdt localization merge [<output>] --bundles <bundle1> <bundle2> [<bundle3> ...]

Update message bundle with a new template bundle:

    fdt localization update <output> <bundle> [--output-to-stdout]

Output a table with information about all messages in a message (template) bundle:

    fdt localization messages <bundle> [--search-in <search text>] [--search-out <search text>] [--search-package <search text>] [--search-file <search text>] [--with-conflicts] [--without-conflicts] [--with-out] [--without-out] [--no-table]

### Schema

Output a table with information about all attributes in a schema:

    fdt attributes [--schema <schemaPath>] [--columns name ns use defaultvalue ...]

Output schema information about a specific attribute, including all its definitions:

    fdt attribute <attributeName> [--schema <schemaPath>]

Output a table with information about all elements in a schema:

    fdt elements [--schema <schemaPath>] [--columns name ns local desc atts ...]

Output schema information about a specific element, including detailed content model info:

    fdt element <elementName> [--schema <schemaPath>]

Output a table with information about all schemas:

    fdt schemas [--columns package locations path]

Output a table with information about all simple types in a schema:

    fdt simpletypes [--columns name variety format]

### Operations

Output a table with information about all operations in a repository:

    fdt operations [--columns name file label desc key ...]

Output information about a specific operation:

    fdt operation <operationName>

### Connectors

Initialize a Fonto Connectors instance in an empty or non-existent directory:

    fdt connectors init [--location <path>] [--version <version>]

Run a Fonto Connectors instance with a self-signed certificate to test your configuration:

    fdt connectors run [--location <path>] [--config-location <path>]

Build a Fonto Connectors docker image for production use:

    fdt connectors build [--location <path>] [--image-name <image-name>] [--image-tag <image-tag>]

Upgrade an existing Fonto Connectors instance to the specified version:

    fdt connectors upgrade [--location <path>] [--version <version>] [--non-interactive]

Download a self-contained build:

    fdt connectors download-self-contained [--version <version>] --runtime <runtime> [--location <path>]

### Content Quality

Initialize a Fonto Content Quality instance in an empty or non-existent directory:

    fdt content-quality init [--location <path>] [--version <version>]

Run a Fonto Content Quality instance to test your configuration:

    fdt content-quality run [--location <path>] [--config-location <path>] [--port]

Build a Fonto Content Quality docker image for production use:

    fdt content-quality build [--location <path>] [--image-name <image-name>] [--image-tag <tag>]

Upgrade an existing Fonto Content Quality instance to the specified version:

    fdt content-quality upgrade [--location <path>] [--version <version>] [--non-interactive]

Download a self-contained build:

    fdt content-quality download-self-contained [--version <version>] --runtime <runtime> [--location <path>]

### Document History

Download a self-contained build:

    fdt document-history download-self-contained [--version <version>] --runtime <runtime> [--location <path>]

### Review

Download a self-contained build:

    fdt review download-self-contained [--version <version>] --runtime <runtime> [--location <path>]

### Schema Compiler

Download a self-contained build:

    fdt schema-compiler download-self-contained [--version <version>] --runtime <runtime> [--location <path>]

### Spell Checker

Download a self-contained build:

    fdt spell-checker download-self-contained [--version <version>] --runtime <runtime> [--location <path>]