## Build Tool Chain

In diesem Abschnitt werden die technischen Voraussetzungen für die Erstellung von im Browser lauffähigem Code und und die Installation und Verwendung der Entwicklungsumgebung erläutert.

### Voraussetzungen

Dieses Projekt wurde entwickelt auf Basis von [nodejs] unter Verwendung von [npm] als Paket-Manager. Mit den folgenden Versionen wurde zuletzt getestet:

```
nodejs: v14.4.0
   npm:  6.14.4
```

Alle Abhängigkeiten sind definiert in der `npm` Konfigurations-Datei `package.json`. Wie üblich werden diese installiert mit dem Befehl `npm install`. Als Task-Manager dieses Projekts wird [gulp] dabei global installiert.

Für das Erstellen der Dokumentation aus den einzelnen *Markdown*-Dateien, die im Verzeichnis `doc/` liegen, wird [pandoc] verwendet. Dieses ist für viele Betriebssysteme und Distributionen verfügbar, muss aber gesondert installiert werden.

### Konfiguration

Die Build Konfiguration ist in `config.js` im Wurzelverzeichnis definiert. Außerdem sind in der Datei `package.json` die zu unterstützenden Browser-Versionen für `autoprefixer` angegeben.

Konfigurationen für Babel, Editoren und *Linter* sind ebenfalls im Wurzelverzeichnis zu finden:

```
       babel: .babelrc
editorconfig: .editorconfig
        html: .htmlhintrc
  javascript: .eslintrc.yml
        sass: .sass-lint.yml
```

### Erstellen von Builds

Alle Schritte zum Erstellen von Builds sind in den Javascript-Dateien unter `tasks/` definiert und werden von der `gulp` Konfigurationsdatei `gulpfile.babel.js` importiert. Dort sind die Teilschritte in *Tasks* zusammengefasst, die man am häufigsten benötigt.

```
$ gulp        # Default task, Kurzform für 'gulp watch'
$ gulp build  # Erstellt einen Development Build
$ gulp watch  # Erstellt einen Development Build und startet den Entwicklungsserver
```
#### Build Target

Die Unterscheidung zwischen Development und Production Build wird anhand der `nodejs` Umgebungsvariable `NODE_ENV` vorgenommen. Ohne diese Angabe wird immer ein Development Build erstellt (siehe `config.js`). Für das Development Target werden Javascript und CSS zusätzlich mit *Sourcemaps* versehen, für die Produktiv-Version dagegen werden die Dateien von unnötigem Ballast befreit (`terser` für Javascript, `cssnano` für CSS).

```
# Erstellen eines Production Build
$ NODE_ENV=production gulp build
```
#### Build Mode

Zusätzlich gibt es für dieses Projekt die Unterscheidung zwischen 'online' und 'offline' Versionen. Im Fall der 'online' Version wird auf eine API zugegriffen, um die benötigten Inhalte zu laden, und um die Antworten der Benutzer zu speichern, um ihnen einen Vergleich mit Anderen zu ermöglichen. Diese Unterscheidung kann beim Aufruf von gulp auf der Kommandozeile mit einem Parameter getroffen werden. Soweit verfügbar, wird standardmäßig der 'online' Modus verwendet, (siehe `config.js`).

```
# Erstellen eines Development Build für den 'offline' Modus
$ gulp --api-mode=offline
```

#### npm Shortcuts

Da die Handhabung mit dem Setzen der Umgebungsvariable und das Übergeben des Parameters etwas umständlich ist, sind in `package.json` `npm` ein paar Shortcuts definiert, z.B.:

```
# Erstellen eines Production Build für den 'offline' Modus per gulp Script
$ NODE_ENV=production gulp build --api-mode=offline

# Erstellen eines Production Build für den 'offline' Modus per npm Script
$ npm run build:prod:offline
```

### Erstellen der Dokumentation

Die Dokumentation in einzelne *Markdown*-Dateien aufgeteilt, die im Verzeichnis `doc/` liegen. Zum Erstellen einer zusammenhängender Dokumentation sind folgende `npm` Scripts definiert, die auf `pandoc` basieren:

```
npm build:doc       // Kurzform für das Erstellen der Dokumentation im bevorzugten Ausgabeformat (Standard: Markdown)
npm build:doc:html  // Erstellt eine HTML Dokumentation als `index.html` in `doc/html`
npm build:doc:md    // Erstellt eine zusammenhängende Dokumentation als `readme.md` im Wurzelverzeichnis
```

### Konventionen

Der Javascript Code ist in ES6 (bzw. ES2015) verfasst. Als CSS-Preprocessor wird Sass mit der `scss` Syntax verwendet. Die Code Style Konventionen wurden von den ursprünglichen Entwicklern übernommen und nur an wenigen Stellen leicht angepasst.

Das Projekt verwendet [editorconfig] für die Integration dieser Konventionen in Editoren, die entsprechende Datei heißt `.editorconfig`.

Für die statische Überprüfung des Quellcodes werden folgende *Linter* verwendet:

- Javascript: [eslint]
- Sass: [sass-lint]
- HTML: [HTMLHint]

Die zugehörigen Konfigurationsdateien befinden sich im Root-Verzeichnis, wie oben in der Auflistung angegeben.

[editorconfig]: http://editorconfig.org
[eslint]: https://eslint.org
[gulp]: https://gulpjs.com/
[HTMLHint]: https://github.com/htmlhint/HTMLHint
[nodejs]: https://nodejs.org
[npm]: https://www.npmjs.com/
[pandoc]: https://pandoc.org
[sass-lint]: https://github.com/sasstools/sass-lint