diff --git a/depends/README.packages b/depends/README.packages
index c35abfbdc1..5ab7ed7dee 100644
--- a/depends/README.packages
+++ b/depends/README.packages
@@ -65,10 +65,22 @@ These variables may be set to override or append their default values.
   $(package)_config_env
   $(package)_build_env
   $(package)_stage_env
+  $(package)_build_opts
+  $(package)_config_opts
 
 The *_env variables are used to add environment variables to the respective
 commands.
 
+Many variables respect a debug/release suffix as well, in order to use them for
+only the appropriate build config. For example:
+  $(package)_cflags_release = -O3
+  $(package)_cflags_i686_debug = -g
+  $(package)_config_opts_release = --disable-debug
+
+These will be used in addition to the options that do not specify
+debug/release. All builds are considered to be release unless DEBUG=1 is set by
+the user.
+
 Other variables may be defined as needed.
 
 Build commands:
diff --git a/depends/README.usage b/depends/README.usage
index 0aacefbf94..d3c57956f1 100644
--- a/depends/README.usage
+++ b/depends/README.usage
@@ -22,6 +22,7 @@ FALLBACK_DOWNLOAD_PATH: If a source file can't be fetched, try here before givin
 NO_QT: Don't download/build/cache qt and its dependencies
 NO_WALLET: Don't download/build/cache libs needed to enable the wallet
 NO_UPNP: Don't download/build/cache packages needed for enabling upnp
+DEBUG: disable some optimizations and enable more runtime checking
 
 If some packages are not built, for example 'make NO_WALLET=1', the appropriate
 options will be passed to bitcoin's configure. In this case, --disable-wallet.