Adapt setup instructions for externally managed Python versions

Tutorials/get-the-tutorials.md

@@ -7,13 +7,17 @@ SPDX-License-Identifier: CC-BY-SA-4.0
 SPDX-FileCopyrightText: 2024 seL4 Project a Series of LF Projects, LLC.
 ---
 
-# Getting the tutorials
 ## Python Dependencies
+
+*Hint:* This step only needs to be done once, i.e. before doing your first tutorial.
+
 The CAmkES python dependencies are required to build the [tutorials](ReworkedTutorials). To install you can run:
-```
+
+```sh
 pip3 install --user camkes-deps
 ```
-*Hint:* This step only needs to be done once, i.e. before doing your first tutorial.
+
+{% include pip-instructions.md %}
 
 ## Get the code
 All code for the tutorials is described in the <a href="https://github.com/seL4/sel4-tutorials-manifest">sel4-tutorials-manifest</a>. Get the code with:

_includes/pip-instructions.md

@@ -0,0 +1,30 @@
+{% comment %}
+SPDX-License-Identifier: CC-BY-SA-4.0
+SPDX-FileCopyrightText: Copyright 2025 UNSW, Sydney
+{% endcomment %}
+{% assign deps = include.deps | default: "camkes-deps" %}
+{% assign venv = include.venv | default: "seL4-venv" %}
+
+<details>
+  <summary>Error: Python environment is externally managed</summary>
+  <div markdown="1">
+
+Some Linux distributions have changed how Python is managed. If you get an error
+saying the Python 'environment is externally managed' follow the instructions
+below. The first two steps are needed only once for setup.
+
+```sh
+python3 -m venv {{venv}}
+./{{venv}}/bin/pip install {{deps}}
+```
+
+The following step is needed every time you start using the build environment
+in a new shell.
+
+```sh
+source ./{{venv}}/bin/activate
+```
+
+It is not important where the `{{venv}}` directory is located.
+  </div>
+</details>

content_collections/_dependencies/camkes.md

@@ -16,6 +16,8 @@ The Python dependencies required by the CAmkES build toolchain can be installed
 pip3 install --user camkes-deps
 ```
 
+{% include pip-instructions.md %}
+
 ### Haskell Dependencies
 
 The CAmkES build toolchain additionally requires Haskell. You can install the [Haskell stack](https://haskellstack.org) on your distribution by running:

content_collections/_dependencies/sel4.md

@@ -91,8 +91,9 @@ The dependencies listed in our Docker files [repository](https://github.com/seL4
 Regardless of your Linux distribution, python dependencies are required to build seL4, the manual and its proofs. To install you can run:
 
 ```sh
-pip3 install --user setuptools
-pip3 install --user sel4-deps
+pip3 install --user setuptools sel4-deps
 ```
 
 (Some distributions use `pip` for python3, others use `pip3`.  Use the Python 3 version for your distribution)
+
+{% include pip-instructions.md deps="sel4-deps" %}