---
title: "Install TauDEM"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Install TauDEM}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

Installing TauDEM actually means installing 3 tools:

* GDAL that TauDEM uses under the hood;
* MPI that R will call to launch TauDEM;
* TauDEM itself.

Please follow instructions on how to install TauDEM, GDAL and MPI depending on your operating system, then finalize your installation as specified below.

No matter your operating system, **take note of the steps you follow**.
This way, if anything goes wrong, you will be able to open an informative bug report and get help more easily.

## Windows

You're in luck! 
The TauDEM Windows installer will install all three tools at once! 
Refer to <https://hydrology.usu.edu/taudem/taudem5/downloads.html>.


## macOS

To install the dependencies, [Homebrew][1] is recommended. It is a
package manager, similar to APT on Linux systems.

1. Open a terminal.

2. Download and install GDAL, MPICH and CMake:
    ```sh
    brew install gdal mpich cmake
    ```
    
3. Go to the [Github page of TauDEM][2] and download the code as ZIP

4. Extract it and move the folder `TauDEM-Develop` to a convenient place, e.g.:
    ```sh
    /Users/$USER/Documents/TauDEM
    ```
    
5. Go back to the terminal and go into the directory with:
    ```sh
    cd /Users/$USER/Documents/TauDEM/TauDEM-Develop
    ```
    
6. Create a folder where the executables will be installed in:
    ```sh
    mkdir bin
    ```
    
7. Go into the source folder `src`: 
    ```sh
    cd src
    ```
 
8. Create the `build` directory: and go into with: 
    ```sh
    mkdir build
    ``` 

9. Go into the `build` directory: 
    ```sh
    cd build
    ``` 
    
10. Build with `cmake ..`

11. Finalize with:

   ```sh
   make && sudo make install
   ```
   
   The executable files will end up in `/usr/local/taudem/`.

12. Add the location of the executable files to your path environment variable. This is a bit tricky
    on macOS, since RStudio and the package only see the path added to `/etc/paths.d/`. So add it  
    with the following two commands:
    
    ```sh
    echo "/usr/local/taudem/" > taudem
    sudo mv taudem /etc/paths.d/
    ```

[1]: https://brew.sh
[2]: https://github.com/dtarb/TauDEM

## Linux

### GDAL

Do you need to install GDAL? In a terminal try `gdalinfo --version`, if it fails `gdal-config --version`. If it works and return something you do not need to install GDAL unless you want a newer version.
You might have installed GDAL in the past for, say, using the sf R package.

If you need to, install GDAL using the official [GDAL docs](https://gdal.org/download.html) (or refer to [TauDEM README](https://github.com/dtarb/TauDEM/) for further suggestions). 


### MPI

First try running `mpiexec --version` in a terminal.
If it works and returns something, you do not need to install MPI unless you want a newer version.

If you need to, install MPI using the official [MPI docs](https://www.open-mpi.org/software/ompi/v4.1/) (or refer to [TauDEM README](https://github.com/dtarb/TauDEM/) for further suggestions). 



### TauDEM

First you need to obtain TauDEM source for GitHub <https://github.com/dtarb/TauDEM/>.
If you are at ease with this, you can clone the repository.
If not, find the green button that allows you to clone, open (with GitHub CLI) or download, and download the ZIP version.

We recommend using CMake because that is what we did but [TauDEM README](https://github.com/dtarb/TauDEM/) also has a method using Make.
Therefore,

* install CMake or Make (check it's not already installed);
* follow [TauDEM README](https://github.com/dtarb/TauDEM/) for further suggestions) for either CMake or Make depending on what you decided to use.

> If the installation shows errors, try using <https://github.com/maelle/TauDEM/tree/more-mpi-deprecations> instead.

> Even for a successful installation you might see many warnings.

In particular, the following error has been observed in some systems: 

```sh
linklib.h: In function ‘bool sendLink(int32_t, int)’:
linklib.h:281:9: error: ‘MPI_Type_extent’ was not declared in this scope; did you mean ‘MPI_Type_get_extent’?
```

In such a case, execute the following commands on the terminal:

```sh
mkdir bin
cd src
sed -i -e 's/MPI_Type_struct/MPI_Type_create_struct/g' linklib.h
sed -i -e 's/MPI_Type_extent(MPI_LONG, \&extent)/MPI_Aint lb\;MPI_Type_get_extent(MPI_LONG, \&lb, \&extent)/g' linklib.h
make
```

See also <https://github.com/lucarraro/traudem/issues/48#issue-2109770271> for details.


```{r, child="../man/fragments/_sitrep.Rmd"}
```