Setting Up WhiteboxTool

WhiteboxTools is a stand-alone executable command-line program with no actual installation. Download the appropriate file for your system from the GitHub site or from the Geomorphometry and Hydrogeomatics Research Group homepage and decompress the folder. Pre-compiled binaries can be downloaded for MS Windows, MacOS, and Linux operating systems. Depending on your operating system, you may need to grant the WhiteboxTools executable file execution privileges before running it.

If you intend to use WhiteboxTools from the command prompt (i.e. a terminal application), you may wish to add the directory containing the WhiteboxTools executable file to your system PATH variable. Doing so will greatly simplify usage of the library from your terminal. Instructions for doing this depend on your operating system and can be found on the Internet.

If you intend to use the Python programming interface for WhiteboxTools you will need to have Python 3 installed. Please note that the Python interface will not work correctly with Python 2. If your system has Python 2 as the default Python version, it is possible to install Python 3 alongside your current version. You may need to use the python3 command in place of the usual python if this is the case.

Building WhiteboxTools From Source Code

Most users rely on the pre-compiled versions of WhiteboxTools and will never need to compile the software from its source code. There are two circumstances under which you may find that you need to build your own binary executable: 1) if you need a binary compiled for a platform other than the project-supported operating systems, and 2) if you require a bleeding-edge feature or bug-fix only available in the development branch. It is likely that WhiteboxTools will work on a wider variety of operating systems and architectures than those of the distributed pre-compiled binaries. If you do not find your operating system/architecture in the list of available WhiteboxTool binaries, then compilation from source code will be necessary. WhiteboxTools can be compiled from the source code with the following steps:

  1. Install the Rust compiler; Rustup is recommended for this purpose. Further instruction can be found at this link.

The proper way to install Rustup depends on your operating system and instructions can be found on the Rust install page. For Unix-type OSs (including linux and MacOS), the recommended install command is:

curl https://sh.rustup.rs -sSf | sh

After installing Rustup, install the Rust compiler and tools (including the Cargo package manager and build tool):

rustup install stable

Note, you may need to install a linker in addition to the Rust compiler (e.g. MS Visual C++ 2015 Build Tools on MS Windows; XCode on MacOS).

  1. Download the WhiteboxTools source code. To download the code, click the green Clone or download button on the GitHub repository site.

  2. Decompress the zipped download file.

  3. Open a terminal (command prompt) window and change the working directory to the whitebox_tools sub-folder, which is contained within the decompressed downloaded Whitebox GAT folder:

>> cd /path/to/folder/whitebox_tools/
  1. Finally, use the rust package manager Cargo, which will be installed alongside Rust, to compile the executable:
>> cargo build --release

Depending on your system, the compilation may take several minutes. When completed, the compiled binary executable file will be contained within the whitebox_tools/target/release/ folder. Type ./whitebox_tools --help at the command prompt (after changing the directory to the containing folder) for information on how to run the executable from the terminal.

The '>>' is shorthand used in this document to denote the command prompt and is not intended to be typed.

Be sure to follow the instructions for installing Rust carefully. In particular, if you are installing on Microsoft Windows, you must have a linker installed prior to installing the Rust compiler (rustc). The Rust webpage recommends either the MS Visual C++ 2015 Build Tools or the GNU equivalent and offers details for each installation approach.