7 minutes to read
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.
This guide explains how to set up docToolchain in the following environments:
A MacOS with bash
Linux/WSL2 with bash
Windows with PowerShell
Windows with cmd.exe
All you need to work with docToolchain is a wrapper script taking care of everything. This wrapper:
Ensures that everyone using your repository uses the same docToolchain version.
Keeps all docToolchain technology out of your repository.
Wraps your commands and directs them to your local installation.
Checks your docToolchain installation. If not installed, the wrapper will do it for you via direct download or Docker.
Did you already work with an older version of docToolchain? Please note that the way it is installed has changed since the v2.x release.
|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.|
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, type the following:
cd <your project> curl -Lo dtcw doctoolchain.github.io/dtcw chmod +x dtcw
If you don’t have
curl installed, you can also use
cd <your project> wget doctoolchain.github.io/dtcw chmod +x dtcw
Since you run docToolchain without Docker, you must get the right Java-Runtime/JDK:
Next, type the following:
./dtcw tasks --group=doctoolchain
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
cd <your project> curl -Lo dtcw.bat doctoolchain.github.io/dtcw.bat
In order to support development for your project on both Linux and Windows, it makes sense to download all three
Let the Wrapper Use a New docToolChain Release
If you have just downloaded the wrapper, there is no need to do this. In this case, just skip to Run your First Command.
If there is a new docToolChain release you wish to use, do the following:
dtcwbash script (.sh, .ps1 and .bat) in your favourite text 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.
If you want to test a not-yet-released feature, you can set the
pullthe current default branch of the project. Please note this only works with a local copy, not with a Docker install.
If you want to develop new features for docToolchain, you can also use
latestdevas version. In this case,
dtcwwill try to clone the docToolChain repository with the ssh-git protocol to a fork in
Run your First Command
To get started with docToolchain, run
tasks as the first command:
./dtcw tasks --group=doctoolchain
.\dtcw.ps1 tasks --group=doctoolchain
dtcw.bat tasks --group=doctoolchain
This command shows all docToolchain tasks and verifies that docToolchain is installed by doing the following:
It checks for a configuration file and creates one if it does not exist. Prefers a local installation.
It makes use of Docker (if available) where there is no local installation.
|If this is your first time installing docToolchain, downloading might take a while.|
If Docker is not available, it downloads and installs docToolchain to your home folder.
It then runs a Gradle build through the Gradle wrapper. If this is your first time, it will download and install Gradle.
The Gradle build also fetches 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
./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
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.
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.