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.

Installing docToolchain

Ralf D. Müller 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

7 minutes to read

Getting the Wrapper

Basically all you need to work with docToolchain is a simple wrapper script taking care of everything. (If you already worked with an older version of docToolchain please note that the way it is installed has changed since the v2.x release.)

This wrapper helps by:

  • Ensuring that everyone using your repository uses the same docToolchain version.

  • Keeping all docToolchain technology out of your repository.

  • Wrapping your commands and directing them to your local installation.

  • Checking your docToolchain installation (if not installed, the wrapper will do it for you via direct download or Docker).

This guide explains how to set up docToolchain in the following environments:

  • A Linux/WSL2 with bash

  • Windows with PowerShell

  • Windows with cmd.exe

Please select the appropriate setup and follow these instructions to install docToolchain step by step.

If you are going to use docToolchain in different projects install the dtcw (docToolchainWrapper) for each one. docToolchain itself will only be installed once in your home folder.
Linux / MacOS / WSL2 with bash
cd <your project>
curl -Lo dtcw doctoolchain.github.io/dtcw
chmod +x dtcw

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

cd <your project>
wget doctoolchain.github.io/dtcw
chmod +x dtcw
if you run on apple silicon (M1/M2), make sure that you have docker up and running or enter a x86 shell by executing arch -x86_64 /bin/bash.
if you run docToolchain without docker, it makes sense to get the right Java-Runtime/JDK by executing ./dtcw getJava
Windows with Powershell
cd <your project>
Invoke-WebRequest doctoolchain.github.io/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.github.io/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 order to support development for your project on both, Linux and Windows, it makes sense to download all three scripts to your project.
dtcw uses bash as shell and thus tries to find java from within bash. Chances are that when you use dtcw from another shell like zsh, you shell knows about the right java version but your bash doesn’t. In that case, please switch to bash and make sure that the right java version is known. Afterwards, you can switch back to your shell.

Configure the Wrapper

There is no need to configure the wrapper itself if you have just downloaded it. In this case, just skip to Running your First Command.

But from time to time you should check github to see if there are new releases you want to use.

In this case, open dtcw in your favourite editor and look for the VERSION-line at the start of the file:

# find official release versions on github:
# https://github.com/docToolchain/docToolchain/releases
# set VERSION to "latest" to get the unreleased latest version
VERSION=2.0.5

Update it to match the latest release and and everything will be updated with the next run.

this will not update the wrapper (dtcw) itself. If you think you should update the wrapper, please re-install it.

There are some situation where you want to test a not-yet-released feature. In such a case, you can set the VERSION to latest and dtcw will clone or pull the current default branch of the project.

This only works with a local copy, not with a docker install.

You can also use latestdev as version. In this case, dtcw will try to clone the repository with the ssh-git protocoll. This way, you can easily point it to your fork and develop new features for docToolchain. You will find the fork in $HOME/.doctoolchain/docToolchain-latest.

latest and latestdev currently only work with the bash version of the wrapper.

Running your First Command

To get started with docToolchain, run tasks as the first command:

Linux / WSL2 with bash
./dtcw tasks --group=doctoolchain
Windows with Powershell
./dtcw.ps1 tasks --group=doctoolchain
Windows with cmd.exe
dtcw.bat tasks --group=doctoolchain

This command shows all docToolchain tasks and verifies that docToolchain is installed by doing the following:

  • Checking for a configuration file (and create one if none exist). Prefers a local installation.

  • Making use of Docker (if available) where there is no local installation.

If this is your first time installing docToolchain, the images download might take a while.

  • if docker is not available, it will download and install docToolchain to your home folder

    • it will then run a gradle build through the gradle wrapper. If this is your first time, it will download and install gradle.

    • the gradle build will also fetch some dependencies. This will also take a while if run for the first time..

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
./gradlew generateHTML -PmavenRepository=your_maven_repo -PmavenUsername=your_username -PmavenPassword=your_pw --info

You’ll notice the installation is an incremental process and will take a while because of all the additional dependencies needed. After the first few commands, you’ll have all the required dependencies installed and things will run faster.

=== Problems & solutions

==== dtcw doesn’t run

You might get an error similiar 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.