Help: configure_file: add $CACHE{VAR} and $ENV{VAR} to description

The configure_file(...) and string(CONFIGURE ...) functions also substitutes variables of the form: $CACHE{VAR} and $ENV{VAR}.

Therefore add this information to the help documentation so that this behavior is described to users

---

The following code snippet shows that $CACHE{VAR} and $ENV{VAR} are also properly supported by configure_file(...) and string(CONFIGURE ...).

# test.in file.
VAR current scope var value: ${VAR}
VAR cache var value:         $CACHE{VAR}
VAR environment var value:   $ENV{VAR}

and the CMake snippet, test.cmake:

cmake_minimum_required(VERSION 3.20)                                                                                                                                         
                                                                                                                                                                             
set(ENV{VAR} "env value")                                                                                                                                                    
set(VAR      "cache value" CACHE INTERNAL "")                                                                                                                                
set(VAR      "current scope value")                                                                                                                                          
                                                                                                                                                                             
set(current_var "\${VAR}")                                                                                                                                                   
set(cache_var   "\$CACHE{VAR}")                                                                                                                                              
set(env_var     "\$ENV{VAR}")                                                                                                                                                
                                                                                                                                                                             
message("Current scope var string:  ${current_var}")                                                                                                                         
message("Cache variable var string: ${cache_var}")                                                                                                                           
message("Env variable string:       ${env_var}")                                                                                                                             
message("")                                                                                                                                                                  
                                                                                                                                                                             
string(CONFIGURE "${current_var}" expanded_current)                                                                                                                          
string(CONFIGURE "${cache_var}"   expanded_cache)                                                                                                                            
string(CONFIGURE "${env_var}"     expanded_env)                                                                                                                              
                                                                                                                                                                             
message("Current scope val:  ${expanded_current}")                                                                                                                           
message("Cache variable val: ${expanded_cache}")                                                                                                                             
message("Env variable val:   ${expanded_env}")                                                                                                                               
                                                                                                                                                                             
configure_file(test.in test.out)                                 

The scripts sets VAR in different scopes (current, cache and environment) and then calls both string(CONFIGURE ...) and configure_file(...) to see that they are properly expanded.

Result of running the script:

$  cmake -P test.cmake                                                                                                                                         
Current scope var string:  ${VAR}
Cache variable var string: $CACHE{VAR}
Env variable string:       $ENV{VAR}

Current scope val:  current scope value
Cache variable val: cache value
Env variable val:   env value

and the test.out result:

$ cat test.out
# test.in file.                                                                                                                                                              
VAR current scope var value: current scope value
VAR cache var value:         cache value
VAR environment var value:   env value