[WIP] Added --cache-dir flag and test.

[bdbaddog]

Test copied from @mwichmann 's feature/cachdir-opt branch

doc and readme/etc forthcoming

Copied from @mwichmann comment below:

A checklist of things to work out. This was supposed to be a simple change (cough, cough).

• [ ] How does cmdline option interact with method calls? Right now, CacheDir enables and creates a "global" cache that applies to all envs; env.CacheDir enables and creates for only env, so the interaction is clear if both are present. For cmdline call, assume it overrides the global CacheDir, as that would be consistent with other options. But what happens if --cache-dir and env.SetOption are both present? See attached test template.
• [ ] CLI cachedir path should be stored in some kind of normalized form, else each environment will make it's own taking the path as relative to the SConscript directory (see attached test - cache1 crreated in both top dir and in src.
• [ ] Top-relative path doesn't work.
• [ ] The --cache-debug file is an only-one thing, but it looks like the logic can open this several times, which isn't great. It was originally opened in write mode, which meant a second open clobbered info from the first. For now, it's being opened in append more to not lost logged data. Possibly debug info should store in class attributes, rather than instance?
• [ ] Would it be better to use logging for the cache debug output than driect writes?

Possible test for multiple global cache specifications cachedir-cli.tar.gz

Contributor Checklist:

• [X] I have created a new test or updated the unit tests to cover the new/changed functionality.
• [ ] I have updated CHANGES.txt and RELEASE.txt (and read the README.rst).
• [ ] I have updated the appropriate documentation

[mwichmann]

index 98725d5ed..dbc60c415 100644
--- a/doc/man/scons.xml
+++ b/doc/man/scons.xml
@@ -708,6 +708,20 @@ derived-file cache specified by &f-link-CacheDir;.</para>
   </listitem>
   </varlistentry>
 
+  <varlistentry id="opt-cache-dir">
+  <term>-<option>-cache-dir=<replaceable>cachedir</replaceable></option></term>
+  <listitem>
+<para>Enable derived-file caching globally, using
+<replaceable>cachedir</replaceable> as the cache directory.
+An individual &consenv; may still specify a different
+cache directory by calling &f-link-env-CacheDir;.
+</para>
+<para><emphasis>Added in version NEXT_RELEASE.</emphasis></para>
+  </listitem>
+  </varlistentry>
+
+  <varlistentry>
+
   <varlistentry id="opt-cache-disable">
   <term>
     <option>--cache-disable</option>,

Questions:

1. There's a list of cache options in the --interactive section listed as affecting build. Should add there?
2. Do you prefer "Added in NEXT_RELEASE" or "New in NEXT_RELEASE". I seem to have used both in the manpage.
3. In the actual add_option, the argument is capitalized (CACHEDIR). Should it be in the manpage also? (don't believe that's consistent at the moment).

[mwichmann]

A checklist of things to work out. This was supposed to be a simple change (cough, cough).

• [ ] Does command-line cachedir override global cachedir if both specified? See attached test template.
• [ ] CLI cachedir path should be stored in some kind of normalized form, else each environment will make it's own taking the path as relative to the SConscript directory (see attached test - cache1 crreated in both top dir and in src.
• [ ] Top-relative path doesn't work.
• [ ] The --cache-debug file is an only-one thing; it looks like the logic can open this several times, which isn't great. It was originally opened in write mode, which meant a second open clobbered info from the first. For now, it's being opened in append more to not lost logged data. Possibly debug info should store in class attributes, rather than instance?
• [ ] Would it be better to use logging for the cache than driect writes?

Possible test for multiple global cache specifications cachedir-cli.tar.gz