From 21371ccd62bbddd3dd6500a2663df83c9a6bad19 Mon Sep 17 00:00:00 2001
From: Alex Lutay <1928266+taurus-forever@users.noreply.github.com>
Date: Tue, 19 Mar 2024 13:20:39 +0100
Subject: [PATCH] Update CONTRIBUTING.md to represent the recent build
 improvements/dependencies

* install all the necessary build dependencies
* document and avoid the possible pitfails
---
 CONTRIBUTING.md | 42 +++++++++++++++++++++++++++++++++++++++---
 1 file changed, 39 insertions(+), 3 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 303f8a3eca..5c8540ce48 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -40,13 +40,49 @@ tox                      # runs 'lint' and 'unit' environments
 
 ## Build charm
 
-Build the charm in this git repository using:
+The build environment assumes that there are preinstalled on the system:
+* [tox](https://tox.wiki/en/4.14.1/)
+* [poetry](https://python-poetry.org/)
+* [charmcraft](https://snapcraft.io/charmcraft)
+* [charmcraftcache](https://pypi.org/project/charmcraftcache/)
+* [pipx](https://python.land/virtual-environments/pipx)
+* [libpq-dev](https://pypi.org/project/libpq-dev/)
+
+To build the charm it is also necessary at least 5GB if free disk space and
+it is recommended to provide 4+ CPU cores and 8GB+ RAM for a decent build speed.
+
+To install all above build dependencies (assuming you are on Ubuntu 22.04 LTS):
 
 ```shell
-tox run -e build-dev
+sudo snap install charmcraft --classic
+
+sudo snap install lxd # should be pre-installed on 22.04
+lxd init --auto       # init LXD (if never used earlier)
+
+sudo apt update && sudo apt install --yes libpq-dev pipx
+
+pipx install poetry
+pipx install charmcraftcache
+pipx ensurepath
+```
+
+Ensure local pip binaries are in your $PATH (otherwise re-login to your shell):
+```shell
+charmcraftcache version
+```
+
+Make sure the install tox version is 4+ (using `tox --version`), if missing OR
+the previos version installed as debian package (topical for Ubuntu 22.04 LTS):
+purge it and install from pip:
+```shell
+sudo apt purge tox && pipx install tox && tox --version
 ```
 
-The tox build environment assumes that there is a preinstalled [poetry](https://python-poetry.org/) on the system.
+Build the charm (inside this Git repository):
+
+```shell
+tox run -e build-dev
+```
 
 ### Deploy