From d0fdf7bc79ee3b97a717666fbde4ab1ba9411e8e Mon Sep 17 00:00:00 2001
From: saturneric <eric@bktus.com>
Date: Sat, 28 Jun 2025 17:31:54 +0200
Subject: docs(appendix): refine setup-dev-env.md for clarity and completeness,
 update instructions for GitHub Codespaces, and add submodule initialization
 step

---
 src/content/docs/appendix/setup-dev-env.md | 50 ++++++++++++++++++++++++------
 1 file changed, 41 insertions(+), 9 deletions(-)

(limited to 'src')

diff --git a/src/content/docs/appendix/setup-dev-env.md b/src/content/docs/appendix/setup-dev-env.md
index a83dd43..5a89123 100644
--- a/src/content/docs/appendix/setup-dev-env.md
+++ b/src/content/docs/appendix/setup-dev-env.md
@@ -12,7 +12,7 @@ that the compilation, build, and testing processes are consistent across
 environments. This approach minimizes integration issues and allows for smoother
 development workflows.
 
-## Leveraging GitHub Codespaces for Rapid Environment Setup
+## Leveraging GitHub Codespaces
 
 To simplify and expedite the setup of a consistent development environment, we
 recommend using GitHub Codespaces. Codespaces offers a cloud-hosted,
@@ -21,7 +21,7 @@ your GitHub Actions workflows. This enables you to quickly create an environment
 that mirrors your CI pipeline, reducing the overhead of manual environment
 configuration.
 
-### Quick Start with GitHub Codespaces
+### Quick Start
 
 [![Open in GitHub
 Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/saturneric/GpgFrontend)
@@ -29,7 +29,7 @@ Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/sat
 With just one click, you can quickly launch a fully configured development
 environment in GitHub Codespaces.
 
-### Manual Setup with GitHub Codespaces
+### Manual Setup
 
 1. Navigate to your GitHub repository.
 2. Click on the Code button and select Open with Codespaces.
@@ -40,7 +40,7 @@ environment in GitHub Codespaces.
 4. The Codespace environment will include all necessary dependencies and tools,
    ensuring consistency with the CI environment.
 
-## Manual Local Environment Setup (If not using Codespaces)
+## Local Environment Setup (without Codespaces)
 
 ### Prerequisites
 
@@ -49,11 +49,34 @@ environment in GitHub Codespaces.
 
 ### Clone the Repository
 
+GitHub:
+
 ```bash
 git clone https://github.com/saturneric/GpgFrontend.git
 cd GpgFrontend
 ```
 
+[BKTUS](https://bktus.com):
+
+```bash
+git clone https://git.bktus.com/GpgFrontend/GpgFrontend.git
+cd GpgFrontend
+```
+
+> Note: The BKTUS repository serves as the main development repository. Many
+> updates and commits are first pushed here for validation and testing before
+> being merged into the public GitHub repository.
+
+After entering the project directory, be sure to initialize and update
+submodules (required for dependencies and third-party libraries):
+
+```bash
+git submodule update --init --recursive
+```
+
+This step is necessary to fetch all required submodules used by the project. If
+you skip this, the build may fail due to missing dependencies.
+
 ### Configure Git Line Endings
 
 This step ensures that line endings are consistent across different operating
@@ -66,29 +89,29 @@ git config --global core.eol lf
 
 ### Install Dependencies
 
-- **On Ubuntu 20.04 or later:**
+- **On Ubuntu 22.04 or later:**
 
 ```bash
 sudo apt-get update
 sudo apt-get install -y build-essential cmake ninja-build libarchive-dev libssl-dev libgpgme-dev
 ```
 
-- **On macOS 12 or later:**
+- **On macOS 13 or later:**
 
 ```bash
 brew install cmake openssl@3 ninja libarchive gpgme
 brew link --force openssl@3
 ```
 
-- **For Windows (via MSYS2):** Set up MSYS2 according to its documentation and
-  install the necessary packages:
+- **For Windows (via MSYS2):** Set up MSYS2 according to [its
+  documentation](https://www.msys2.org/) and install the necessary packages:
 
 ```bash
 pacman -Syu
 pacman -S mingw-w64-x86_64-cmake msys2-runtime-devel mingw-w64-x86_64-ninja mingw-w64-x86_64-gnupg mingw-w64-x86_64-libarchive mingw-w64-x86_64-gpgme
 ```
 
-### Install Qt6 (if applicable)
+### Install Qt6
 
 Use the Qt online installer or your package manager to install Qt6 and the
 required modules for your project.
@@ -101,6 +124,15 @@ $ cmake -G Ninja -DCMAKE_BUILD_TYPE=Debug ..
 $ ninja
 ```
 
+:::caution[Note for v2.1.9]
+
+Starting from version 2.1.9, GpgFrontend requires gpgme 2.0 or newer. However,
+most package managers do not provide a sufficiently recent version of gpgme at
+this time. It is strongly recommended to enable in-tree building of gpgme by
+setting the CMake option: `GPGFRONTEND_LINK_GPGME_INTO_CORE=ON`
+
+:::
+
 ### Notes
 
 - Adjust the build type (`Release`, `Debug`, etc.) as needed.
-- 
cgit v1.2.3