Welcome!

Nice to meet you. Glad that you want to learn more about using docToolchain. Start by installing what you need.

The following steps are the same as described in the User Docs. Please follow them step by step. You are prompted to install everything you need for each step.

If you encounter problems, create a GitHub issue and the community will help you.

Install docToolchain

Michael Rossner igoreq1010 Markus Napp Markus Napp RFUCN Simon rmi2hi Timo Abele Ralf D. Müller Kevin Latka Max Hofer Pascal Euhus Frank Joseph Jochen Kraushaar Miranda Boerlage Nicca3006 Jeremie Bresson Bennykillua Jérémie Bresson T8xi Michael Krauße Ralf D. Müller stehlih Dr. Stefan Pfeiffer Alexander Schwartz feinstaub Jakub J Jablonski jakubjab Jorge Dr. Gernot Starke Lars Francke

11 minutes to read

Installation Overview

docToolchain is composed of two parts:

  • doctoolchain which is the toolchain used to create your documentation

  • the docToolchain shell wrapper script installed in your project which calls the toolchain

The use of this setup has the following advantages:

  • It’s easy to build your documentation within your project folder.

  • Ensures that everyone in the project uses the same docToolchain version.

  • Keeps all docToolchain technology out of your project repository.

  • Facilitates the installation of the docToolchain if not installed.

  • Makes it easier to upgrade to newer versions of docToolchain.

Install dtcw in your project directory

The docToolchain wrapper script dtcw, respective dtcw.ps1 or dtcw.bat for MS Windows, is meant to be installed in your project root directory. The wrapper script simplifies calls to the docToolchain.

Even if you are going to use docToolchain in multiple projects, the toolchain will only be installed once on your system.
Steps for MacOS/Linux/WSL2 with bash

If you have an Apple Silicon (M1/M2) Mac, make sure that you have docker up and running and type the following commands in the Terminal:

`arch -x86_64 /bin/bash`

Now, download dtcw into your project directory and make the script executable with the following commands:

cd <your project>
curl -Lo dtcw https://doctoolchain.org/dtcw
chmod +x dtcw

If you don’t have curl installed, you can also use wget:

cd <your project>
wget doctoolchain.org/dtcw
chmod +x dtcw
Windows with Powershell
cd <your project>
Invoke-WebRequest doctoolchain.org/dtcw.ps1 -Outfile dtcw.ps1
Got an error message that you are not allowed to execute powershell scripts? Try to switch to an unrestricted powershell by executing powershell.exe -ExecutionPolicy Unrestricted.
Windows with cmd.exe
cd <your project>
curl -Lo dtcw.bat doctoolchain.org/dtcw.bat
dtcw.bat wraps the dtcw.ps1 script and executes it in powershell. This might be easier to use if you haven’t yet configured your powershell as a developer.
In case your development team uses different operating systems, put the wrapper scripts for the desired operating systems (dtcw, dtcw.ps1, and dtcw.bat) into your project.

Once the docToolchain wrapper is installed in your project directory you have to decide how to install the toolchain:

docToolchain depends on Java 11 (Java 11, 14, and 17 are also supported)

If you don’t use the docToolchain container image you have to install Java on your system. In case you have Java already installed, make sure JAVA_HOME is set.

You may use dtcw to install the correct Java version, as shown in the next steps.

Run docToolchain in a container

The docToolchain project provides a container image of approximately 900 MB from the Docker Hub container registry. The Dockerfile from which the image is created may be found at https://github.com/docToolchain/docker-image.

To run docToolchain in a container you need an installed container engine. The best known container engine is Docker.

If the container engine is installed you can Run your First Command. The docToolchain wrapper script in your project directory will detect the container engine and pull the docToolchain image on the first invocation.

Use your custom docker image

Some might need to create their own docker image to add additional tooling or configurations, e.g. proxy settings. In this case you can pass the image name via parameter image directly after docker:

./dtcw docker image <image_name> generateHTML
.\dtcw.ps1 docker image <image_name> generateHTML
.\dtcw.bat docker image <image_name> generateHTML

Pass environment variables to docker containers

To pass any environment variable to the docker container you can make use of an environment file. The environment file must have the name dtcw_docker.env and must be located in the same folder as dtcw.

An example content is e.g.:

# set environment variables for docToolchain docker container
PROJECT=TEST_PROJECT
TEAM=TEST_TEAM

Pass additional parameter to docker containers

To pass additional parameters to the docker container you can make use of the parameter extra_arguments followed by a string with the additional parameters.

One usecase is to enable you to set environment variables to dynamic values.

./dtcw docker image <image_name> extra_arguments "--env USER=${USERNAME} --env REPO_LOCATION=`git config remote.origin.url`" generateHTML

Install docToolchain with dtcw

Steps for MacOS/Linux/WSL2 with bash

To install docToolchain in $HOME/.doctoolchain execute the following command.

./dtcw install doctoolchain

In case you have no Java installed you may use dtcw to install Java in a subdirectory of $HOME/.doctoolchain.

./dtcw install java
Unable to locate Java Runtime - check your Bash environment

If dtcw complains about not being able to locate a Java Runtime, make sure Java is found in your Bash shell, the shell used by dtcw.

If you use dtcw from another shell like zsh, it may be that your shell finds the supported Java version but your bash setup doesn’t. In that case, please switch to bash and make sure that a supported Java version is found. Afterwards, you can switch back to your shell.
Windows with Powershell

To install docToolchain in $HOME/.doctoolchain execute the following command.

./dtcw.ps1 install doctoolchain

In case you have no Java installed you can use dtcw.ps1 to install Java:

.\dtcw.ps1 install java
Windows with cmd.exe

To install docToolchain in $HOME/.doctoolchain execute the following command.

./dtcw.bat install doctoolchain

In case you have no Java installed you can use dtcw.ps1 to install Java:

.\dtcw.bat install java

If the docToolchain installation finished successfully, you are ready to Run your First Command.

Install docToolchain with SDKMAN!

TODO: description how to install docToolchain with SDKMAN!.

Run your First Command

Call the docToolchain wrapper with tasks --group doctoolchain to show all tasks provided by docToolchain. Those tasks may be used when invoking the docToolchain wrapper script.

The first time docToolchain is called, it downloads all necessary dependencies. Therefore, the execution of the command may take some time. Subsequent calls to docToolchain will be faster. 
./dtcw tasks --group=doctoolchain
dtcw 0.50 - 8061694f
docToolchain 2.3.0
Available docToolchain environments: local (1)
Environments with docToolchain [2.3.0]: local (2)
Using environment: local (3)
Using Java 17.0.6 [/home/john_doe/.doctoolchain/jdk/bin/java] (4)
Downloading https://services.gradle.org/distributions/gradle-7.5.1-bin.zip (5)
..........10%..........20%..........30%...........40%..........50%..........60%..........70%...........80%..........90%..........100%

Welcome to Gradle 7.5.1!

Here are the highlights of this release:
 - Support for Java 18
 - Support for building with Groovy 4
 - Much more responsive continuous builds
 - Improved diagnostics for dependency resolution

For more details see https://docs.gradle.org/7.5.1/release-notes.html

To honour the JVM settings for this build a single-use Daemon process will be forked. See https://docs.gradle.org/7.5.1/userguide/gradle_daemon.html#sec:disabling_the_daemon.
Daemon will be stopped at the end of the build

> Configure project :

Config file '/code/docToolchainConfig.groovy' does not exist' (6)
[ant:input]
[ant:input] do you want me to create a default one for you? (y, n)
y
1 List of available docToolchain environments. The output may vary depending on your system. In our example only the local environment is available since neither sdk nor docker was found.
2 Environments in which docToolchain s available. The output may vary depending on how you installed docToolchain. In our example docToolchain was found in the user’s local environment in $HOME/.doctoolchain.
3 Shows the used docToolchain environment. In case docToolchain is installed in more than one environment the wrapper script picks the environment in the following order: local, sdk, and then docker.
4 Location of the used Java. In our example Java was installed in the local environment with the docToolchain wrapper script.
5 docToolchain was invoked the first time, thus it is downloading its dependencies.
6 The docToolchain configuration file docToolchainConfig.groovy wasn’t found in the project repository. docToolchain asks if it should create a new one. 
.\dtcw.ps1 tasks --group=doctoolchain
dtcw.bat tasks --group=doctoolchain
If you are behind a corporate proxy, you might need to consider build-script dependencies are fetched from a repository referenced by the property mavenRepository. By default, the value https://plugins.gradle.org/m2/ is used. When a repository requiring credentials is used the properties mavenUsername and mavenPassword can be set as well.
Example command passing a custom maven repository with credentials from the command line
DTC_OPTS="-PmavenRepository=your_maven_repo -PmavenUsername=your_username -PmavenPassword=your_pw" ./dtcw tasks --group=doctoolchain --info

Problems & solutions

dtcw doesn’t run

You might get an error similar to this one:

./dtcw local tasks --group=doctoolchain
./dtcw: line 1: syntax error near unexpected token `newline'
./dtcw: line 1: `<!DOCTYPE html>'

If you see that, it’s likely that the wrapper didn’t download correctly. You can expect that an HTML page was downloaded instead of the wrapper. Please try to redownload the wrapper.

docker throws and error with dtcw

On windows you might get the following error

Error response from daemon: user declined directory sharing C:\Users\path_to_my_folder

This means that docker wanted to share the named folder (possibly the repo) but didn’t have the rights. This means you have to share the folder yourself on docker. Go to docker dashboard → settings → Resources → FileSharing. Add required folder and hit Apply & Restart.

Incompatible Java version

You may see that docToolchain starts but crashes with a stacktrace that starts like this:

* What went wrong:
Could not compile settings file '/Users/falk/.doctoolchain/docToolchain-2.0.0/settings.gradle'.
> startup failed:
  General error during semantic analysis: Unsupported class file major version 61

  java.lang.IllegalArgumentException: Unsupported class file major version 61

In this case, you’ve got an incompatible version of Java. dtcw tries to check the Java version up front by running java --version, but Gradle sometimes picks up a different version. If you get a similar error, try reinstalling a compatible Java version.