From fe7823a249f33779ce76af9ffa4fd757f98e9188 Mon Sep 17 00:00:00 2001 From: stephane Date: Fri, 23 Jan 2015 14:50:03 -0800 Subject: [PATCH] Add documentation of DIB_IMAGE_CACHE variable It is an established convention to use DIB_IMAGE_CACHE in elements to refer to the cache location. This convention has not been documented in the README, unlike other element development practices. This change adds documentation for DIB_IMAGE_CACHE both from an element user and developer perspective. This change was prompted by I76030654e7dfc7b7d4dfa87e082c14e7cee479b9 Change-Id: I6fcc2409450cdb45e5afcb292908fbaee1af258a --- README.rst | 38 ++++++++++++++++++++++++++------------ 1 file changed, 26 insertions(+), 12 deletions(-) diff --git a/README.rst b/README.rst index 5ad961cb..b368ef1c 100644 --- a/README.rst +++ b/README.rst @@ -97,16 +97,20 @@ Caches and offline mode ======================= Since retrieving and transforming operating system image files, git -repositories, Python or Ruby packages, and so on can be a significant overhead, -we cache many of the inputs to the build process in ~/.cache/image-create/. The -writing an element documention describes the interface within -disk-image-builder for caching. When invoking disk-image-builder the --offline -option will instruct disk-image-builder to not refresh cached resources. +repositories, Python or Ruby packages, and so on can be a significant +overhead, we cache many of the inputs to the build process. The cache +location is read from DIB\_IMAGE\_CACHE. The *Writing an element* +section of this document describes the interface within +disk-image-builder for caching. When invoking disk-image-builder, the +``--offline`` option will instruct disk-image-builder to not refresh +cached resources. -Note that we don't maintain operating system package caches, instead depending -on your local infrastructure (e.g. Squid cache, or an APT or Yum proxy) to -facilitate caching of that layer, so you need to arrange independently for -offline mode. +Note that we don't maintain operating system package caches, instead +depending on your local infrastructure (e.g. Squid cache, or an APT or +Yum proxy) to facilitate caching of that layer, so you need to arrange +independently for offline mode. For more information about setting up +a squid proxy, consult the [TripleO +documentation](http://docs.openstack.org/developer/tripleo-incubator/devtest_setup.html#f3). Base images ----------- @@ -239,7 +243,7 @@ named after the element itself. Elements *should* have a README.md in the root of the element directory describing what it is for. Writing an element ------------------ +------------------ Conform to the following conventions: @@ -267,8 +271,15 @@ Conform to the following conventions: and not remounted into the filesystem image - if the mount point is needed again, your element will need to remount it at that point. -Phase Subdirectories -^^^^^^^^^^^^^^^^^^^^ +* If caching is required, elements should use a location under + $DIB\_IMAGE\_CACHE. + +* Elements should allow for remote data to be cached. When + $DIB\_OFFLINE is set, this cached data should be used if + possible. See the *Global image-build variables* section of this + document for more information. + +### Phase Subdirectories ### Make as many of the following subdirectories as you need, depending on what part of the process you need to customise. The subdirectories are executed in @@ -416,6 +427,9 @@ Global image-build variables diskimage-builder is building a disk image. This works only for ext filesystems. +* DIB\_IMAGE\_CACHE : path to where cached inputs to the build process + are stored. Defaults to ~/.cache/image_create. + Structure of an element -----------------------