Developer installation guide#
Here we describe three ways to install HydroMT for development. HydroMT makes use of pixi as a task runner with multiple environments that can be activated.
But first, you need to clone the HydroMT git
repo using
ssh
from github.
Then, navigate into the the code folder (where the pyproject.toml is located)
$ git clone git@github.com:Deltares/hydromt.git
$ cd hydromt
Pixi based installation#
We use pixi as our task runner. For more information about installing pixi please refer to the linked webpage.
Once pixi is installed you can create a developer installation by running the following command:
$ pixi run -e <ENVIRONMENT> install
This will automatically install all dependencies needed to develop HydroMT, and it install HydroMT within the current environment in editable mode.
You can use open-vscode.bat
to open the current folder in VSCode with the correct environment activated.
This bat-file simply runs pixi run -e <ENVIRONMENT> code .
to set up the pixi environment before starting VSCode.
The python installation can be found in the .pixi
folder. No need to switch interpreters.
The ENVIRONMENT
to specify is of your preference, based on what you are going to do.
The most complete environment would be full-py311
/ default
.
Fine tuned installation#
If you want a more fine tuned installation you can also specify exactly which features you’d like to install.
For instance, you can add a new environment in pixi.toml
to install _extra_, _io_ and _doc_ dependencies.
[environments]
my_env = ["extra", "io", "doc"]
We have 7 optional dependency groups you can specify (see pixi.toml
for list of dependencies in each group):
io
: Reading and writing various formats like excel but also cloud file systemsextra
: Couldn’t think of a better name for this one, but it has some extra for ET and mesh calculationsdev
: everything you need to develop and publish HydroMTtest
What you need to run the test suite. Test suite should be setup that only tests that use the dependencies that are installed are run, so this should always pass no matter what other dependencies you may or may not have installed.doc
generate the docsexamples
Run Jupyter notebook examples. Used this for binder support mostly.deprecated
dependencies that we hope to remove soon, but aren’t quite ready to yet.
We also have 3 pre-defined environments. These are more or less just collections of one or more groups designed for common use cases:
min
no optional dependencies. mostly as a base to build your DIY stack on.slim
Just the operational bits, what most people will probably want if you’re using HydroMT, and it’s what the cloud will most likely usefull
absolutely everything, useful for developing.
We also have docker images for each of the flavours available on the deltares dockerhub page.
Adding a dependency#
In order to add a dependency you need to:
Add it to the
pyproject.toml
file in the[project.dependencies]
section.And you need to add it to the
pixi.toml
file in the[dependencies]
section.Then you will need to run
pixi run -e <ENVIRONMENT> install
to install the new dependency. It will update thepixi.lock
file.Commit the changes to the
pyproject.toml
,pixi.toml
, andpixi.lock
files.
Updating dependencies#
The dependencies in pixi are managed via the pixi.toml
and pixi.lock
file.
We commit the pixi.lock
file to the repository to ensure that everyone has the same versions of the dependencies installed.
Since it freezes the dependencies, we will need to schedule regular updates.
Remove the
pixi.lock
file.Run
pixi run -e <ENVIRONMENT> install
to update the dependencies.
There is a Github action workflow that does this on a monthly basis. It will create a pull request with the updated pixi.lock
file.