two changes that make the handling of the download cache match how buildout

does it for easy-install:

- require the download cache (but not namespace directories) to be an
  existing directory in order to catch configuration bugs

- made relative download cache paths refer to the buildout directory

src/zc/buildout/download.py

@@ -56,6 +56,7 @@ class Download(object):
 
     def __init__(self, options={}, cache=-1, namespace=None,
                  offline=-1, fallback=False, hash_name=False, logger=None):
+        self.directory = options.get('directory', '')
         self.cache = cache
         if cache == -1:
             self.cache = options.get('download-cache')
@@ -69,9 +70,14 @@ class Download(object):
         self.logger = logger or logging.getLogger('zc.buildout')
 
     @property
-    def cache_dir(self):
+    def download_cache(self):
         if self.cache is not None:
-            return os.path.join(realpath(self.cache), self.namespace or '')
+            return realpath(os.path.join(self.directory, self.cache))
+
+    @property
+    def cache_dir(self):
+        if self.download_cache is not None:
+            return os.path.join(self.download_cache, self.namespace or '')
 
     def __call__(self, url, md5sum=None, path=None):
         """Download a file according to the utility's configuration.
@@ -98,9 +104,15 @@ class Download(object):
         but will not remove the copy in that case.
 
         """
+        if not os.path.exists(self.download_cache):
+            raise zc.buildout.UserError(
+                'The directory:\n'
+                '%r\n'
+                "to be used as a download cache doesn't exist.\n"
+                % self.download_cache)
         cache_dir = self.cache_dir
         if not os.path.exists(cache_dir):
-            os.makedirs(cache_dir)
+            os.mkdir(cache_dir)
         cache_key = self.filename(url)
         cached_path = os.path.join(cache_dir, cache_key)
 

src/zc/buildout/download.txt

@@ -254,6 +254,15 @@ ChecksumError: MD5 checksum mismatch downloading 'http://localhost/foo.txt'
 
 >>> remove(path)
 
+Finally, let's see what happens if the download cache to be used doesn't exist
+as a directory in the file system yet:
+
+>>> Download(cache=join(cache, 'non-existent'))(server_url+'foo.txt')
+Traceback (most recent call last):
+UserError: The directory:
+'/tmp/tmpZ2cwCfbuildoutSetUp/_TEST_/download-cache/non-existent'
+to be used as a download cache doesn't exist.
+
 Using namespace sub-directories of the download cache
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -453,6 +462,19 @@ option:
 >>> print download.cache_dir
 /download-cache/cmmi
 
+If the ``download-cache`` option specifies a relative path, it is understood
+relative to the current working directory, or to the buildout directory if
+that is given:
+
+>>> download = Download({'download-cache': 'relative-cache'})
+>>> print download.cache_dir
+/sample-buildout/relative-cache/
+
+>>> download = Download({'directory': join(sample_buildout, 'root'),
+...                      'download-cache': 'relative-cache'})
+>>> print download.cache_dir
+/sample-buildout/root/relative-cache/
+
 Keyword parameters take precedence over the corresponding options:
 
 >>> download = Download({'download-cache': cache}, cache=None)

src/zc/buildout/extends-cache.txt

@@ -66,6 +66,7 @@ download cache for it. The configuration cache we specify will be created when
 running buildout and the base.cfg file will be put in it (with the file name
 being a hash of the complete URL):
 
+>>> mkdir('cache')
 >>> write('buildout.cfg', """\
 ... [buildout]
 ... extends = %sbase.cfg
@@ -166,6 +167,8 @@ bases, using different caches:
 
 >>> mkdir('home')
 >>> mkdir('home', '.buildout')
+>>> mkdir('cache')
+>>> mkdir('user-cache')
 >>> os.environ['HOME'] = join(sample_buildout, 'home')
 >>> write('home', '.buildout', 'default.cfg', """\
 ... [buildout]