From 01412331a453ae0eb489285cd3cc1bd8d4e100a4 Mon Sep 17 00:00:00 2001
From: Martin Pecka <peckama2@fel.cvut.cz>
Date: Mon, 2 Jan 2023 15:04:11 +0100
Subject: [PATCH] Documented ROSDEP_CACHE_PATH and ROSDEP_SOURCE_PATH.

Signed-off-by: Martin Pecka <peckama2@fel.cvut.cz>
---
 doc/overview.rst     | 21 +++++++++++++++++++++
 doc/sources_list.rst | 20 ++++++++++++++++++++
 2 files changed, 41 insertions(+)

diff --git a/doc/overview.rst b/doc/overview.rst
index 60d98e65b..f0afa05b6 100644
--- a/doc/overview.rst
+++ b/doc/overview.rst
@@ -29,6 +29,17 @@ rosdep gets its data from.
 ``rosdep update`` reads through this sources list to initialize your
 local database.
 
+You can override the location by setting environment variable
+``ROSDEP_SOURCE_PATH``. The custom path has to exist prior to calling
+``rosdep init``, otherwise the default one will be used.
+
+Please note that when using ``sudo``, environment
+variables from the user are not passed to the command. To specify the variable
+for initializing the database, call::
+
+    sudo mkdir -p /usr/rosdep.sources
+    sudo env ROSDEP_SOURCE_PATH=/usr/rosdep.sources rosdep init
+
 Updating rosdep
 ---------------
 
@@ -36,6 +47,12 @@ You can update your rosdep database by running::
 
     rosdep update
 
+If you have specified a custom ``ROSDEP_SOURCE_PATH``, do not forget to set it
+also for this command.
+
+Default location of the local rosdep database is in ``$HOME/.ros/rosdep``.
+To change it, set environment variable ``ROSDEP_CACHE_PATH``, or pass
+command-line arguments ``--sources-cache-dir`` and ``--meta-cache-dir``.
 
 Installating rosdeps
 --------------------
@@ -95,5 +112,9 @@ dependencies::
 
 
 
+If you specified a custom ``ROSDEP_CACHE_PATH`` or used command-line arguments
+``--sources-cache-dir`` and ``--meta-cache-dir``, you have to pass these to
+all rosdep commands used afterwards, including ``rosdep install``.
+
 For more information, please see the :ref:`command reference <rosdep_usage>`.
 
diff --git a/doc/sources_list.rst b/doc/sources_list.rst
index b083a4389..461016855 100644
--- a/doc/sources_list.rst
+++ b/doc/sources_list.rst
@@ -30,6 +30,26 @@ Sources list file format
 ``/etc/ros/rosdep/sources.list.d``.  ``sudo rosdep init`` will create
 a default configuration for you.
 
+You can override the location by setting environment variable
+``ROSDEP_SOURCE_PATH``. The custom path has to exist prior to calling
+``rosdep init``, otherwise the default one will be used.
+
+Please note that when using ``sudo``, environment
+variables from the user are not passed to the command. To specify the variable
+for initializing the database, call::
+
+    sudo mkdir -p /usr/rosdep.sources
+    sudo env ROSDEP_SOURCE_PATH=/usr/rosdep.sources rosdep init
+
+If you point ``ROSDEP_SOURCE_PATH`` to a user-writable directory, you can avoid
+obtaining root privileges, so you can just call::
+
+    mkdir -p $HOME/my_rosdep_sources
+    ROSDEP_SOURCE_PATH=$HOME/my_rosdep_sources rosdep init
+
+Be aware that ``~`` is not expanded in ``ROSDEP_SOURCE_PATH``, so you should
+specify an absolute path.
+
 rosdep processes the files in this directory, sorted by filename in
 ascending order.  Precedence is assigned to the files in the order
 they are processed, with the first file having the highest