From 023db569e8f7bf325fba86a1fa4ba984026a532c Mon Sep 17 00:00:00 2001
From: Benjamin ROBIN <dev@benjarobin.fr>
Date: Sun, 5 Jan 2025 17:03:52 +0100
Subject: [PATCH 2/2] docs: Update MESA_SHADER_CACHE_DIR env variable behavior

Update documentation to match implementation of
disk_cache_generate_cache_dir().

Signed-off-by: Benjamin ROBIN <dev@benjarobin.fr>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/32886>
---
 docs/envvars.rst         | 21 ++++++++++++---------
 src/util/disk_cache_os.c | 13 +++++++++----
 2 files changed, 21 insertions(+), 13 deletions(-)

diff --git a/docs/envvars.rst b/docs/envvars.rst
index 7247158cc5073..e812b9280777a 100644
--- a/docs/envvars.rst
+++ b/docs/envvars.rst
@@ -200,10 +200,11 @@ Core Mesa environment variables
 .. envvar:: MESA_SHADER_CACHE_DIR
 
    if set, determines the directory to be used for the on-disk cache of
-   compiled shader programs. If this variable is not set, then the cache
-   will be stored in ``$XDG_CACHE_HOME/mesa_shader_cache_db`` (if that
-   variable is set), or else within ``.cache/mesa_shader_cache_db`` within
-   the user's home directory.
+   compiled shader programs. If set then the cache will be stored in
+   ``$MESA_SHADER_CACHE_DIR/mesa_shader_cache_db``. If this variable is not
+   set, then the cache will be stored in
+   ``$XDG_CACHE_HOME/mesa_shader_cache_db`` (if that variable is set), or else
+   within ``.cache/mesa_shader_cache_db`` within the user's home directory.
 
 .. envvar:: MESA_SHADER_CACHE_SHOW_STATS
 
@@ -218,9 +219,10 @@ Core Mesa environment variables
    cache DBs via :envvar:`MESA_DISK_CACHE_READ_ONLY_FOZ_DBS` or
    :envvar:`MESA_DISK_CACHE_READ_ONLY_FOZ_DBS_DYNAMIC_LIST`. This
    implementation does not support cache size limits via
-   :envvar:`MESA_SHADER_CACHE_MAX_SIZE`. If
-   :envvar:`MESA_SHADER_CACHE_DIR` is not set, the cache will be stored
-   in ``$XDG_CACHE_HOME/mesa_shader_cache_sf`` (if that variable is set)
+   :envvar:`MESA_SHADER_CACHE_MAX_SIZE`. If :envvar:`MESA_SHADER_CACHE_DIR`
+   is set, the cache will be stored in
+   ``$MESA_SHADER_CACHE_DIR/mesa_shader_cache_sf``, or else within
+   ``$XDG_CACHE_HOME/mesa_shader_cache_sf`` (if that variable is set)
    or else within ``.cache/mesa_shader_cache_sf`` within the user's home
    directory.
 
@@ -229,8 +231,9 @@ Core Mesa environment variables
    if set to 1, enables the multi file on-disk shader cache implementation
    instead of the default Mesa-DB cache implementation.
    This implementation increases the overall disk usage.
-   If :envvar:`MESA_SHADER_CACHE_DIR` is not set, the cache will be stored
-   in ``$XDG_CACHE_HOME/mesa_shader_cache`` (if that variable is set)
+   If :envvar:`MESA_SHADER_CACHE_DIR` is set, the cache will be stored in
+   ``$MESA_SHADER_CACHE_DIR/mesa_shader_cache``, or else within
+   ``$XDG_CACHE_HOME/mesa_shader_cache`` (if that variable is set)
    or else within ``.cache/mesa_shader_cache`` within the user's home
    directory.
 
diff --git a/src/util/disk_cache_os.c b/src/util/disk_cache_os.c
index 8d6ce428c1823..09051491d332f 100644
--- a/src/util/disk_cache_os.c
+++ b/src/util/disk_cache_os.c
@@ -873,10 +873,15 @@ disk_cache_write_item_to_disk(struct disk_cache_put_job *dc_job,
 
 /* Determine path for cache based on the first defined name as follows:
  *
- *   $MESA_SHADER_CACHE_DIR
- *   $XDG_CACHE_HOME/mesa_shader_cache
- *   $HOME/.cache/mesa_shader_cache
- *   <pwd.pw_dir>/.cache/mesa_shader_cache
+ *   $MESA_SHADER_CACHE_DIR/mesa_shader_cache*
+ *   $XDG_CACHE_HOME/mesa_shader_cache*
+ *   $HOME/.cache/mesa_shader_cache*
+ *   <pwd.pw_dir>/.cache/mesa_shader_cache*
+ *
+ * The directory 'mesa_shader_cache*' is named depending of cache type:
+ *  - For DISK_CACHE_MULTI_FILE: mesa_shader_cache
+ *  - For DISK_CACHE_SINGLE_FILE: mesa_shader_cache_sf
+ *  - For DISK_CACHE_DATABASE: mesa_shader_cache_db
  */
 char *
 disk_cache_generate_cache_dir(void *mem_ctx, const char *gpu_name,
-- 
GitLab