From efec0c226ce5211da93a378bc318be5819620777 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?M=2E=20Fatih=20C=C4=B1r=C4=B1t?=
 <xmfcx@users.noreply.github.com>
Date: Wed, 14 Feb 2024 05:48:34 +0300
Subject: [PATCH] feat: improve ccache documentation with config (#519)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: M. Fatih Cırıt <mfc@leodrive.ai>
---
 .../others/advanced-usage-of-colcon.md        | 51 ++++++++++++++++---
 1 file changed, 43 insertions(+), 8 deletions(-)

diff --git a/docs/how-to-guides/others/advanced-usage-of-colcon.md b/docs/how-to-guides/others/advanced-usage-of-colcon.md
index f6fe1d2d2f9..da845748679 100644
--- a/docs/how-to-guides/others/advanced-usage-of-colcon.md
+++ b/docs/how-to-guides/others/advanced-usage-of-colcon.md
@@ -107,20 +107,55 @@ VERBOSE=1 colcon build --packages-up-to <package_name> --event-handlers console_
 
 For other options, see [here](https://colcon.readthedocs.io/en/released/reference/event-handler-arguments.html).
 
-## Using Ccache
+## Using Ccache to speed up recompilation
 
-[Ccache](https://ccache.dev/) can speed up recompilation.
-It is recommended to use it to save your time unless you have a specific reason not to do so.
+[Ccache](https://ccache.dev/) is a compiler cache that can significantly speed up recompilation by caching previous
+compilations and reusing them when the same compilation is being done again.
+It's highly recommended for developers looking to optimize their build times, unless there's a specific reason to avoid
+it.
 
-1. Install `Ccache`:
+### Step 1: Install Ccache
+
+```bash
+sudo apt update && sudo apt install ccache
+```
+
+### Step 2: Configure Ccache
+
+1. **Create the Ccache configuration folder and file:**
 
    ```bash
-   sudo apt update && sudo apt install ccache
+   mkdir -p ~/.cache/ccache
+   touch ~/.cache/ccache/ccache.conf
    ```
 
-2. Write the following in your `.bashrc`:
+2. **Set the maximum cache size.** The default size is `5GB`, but you can increase it depending on your needs. Here,
+   we're setting it to `60GB`:
 
    ```bash
-   export CC="/usr/lib/ccache/gcc"
-   export CXX="/usr/lib/ccache/g++"
+   echo "max_size = 60G" >> ~/.cache/ccache/ccache.conf
    ```
+
+### Step 3: Integrate Ccache with Your Environment
+
+To ensure Ccache is used for compilation, add the following lines to your `.bashrc` file.
+This will redirect GCC and G++ calls through Ccache.
+
+```bash
+export CC="/usr/lib/ccache/gcc"
+export CXX="/usr/lib/ccache/g++"
+export CCACHE_DIR="$HOME/.cache/ccache/"
+```
+
+After adding these lines, reload your `.bashrc` or restart your terminal session to apply the changes.
+
+### Step 4: Verify Ccache is Working
+
+To confirm Ccache is correctly set up and being used, you can check the statistics of cache usage:
+
+```bash
+ccache -s
+```
+
+This command displays the cache hit rate and other relevant statistics, helping you gauge the effectiveness of Ccache in
+your development workflow.