diskimage-builder/doc/source/developer
Ian Wienand 274be6de55 Making element overriding explicit
This is a re-factor of element_dependencies to achieve two things --
centralising override policy and storing path names.

Firstly we want to make the override policy for elements completely
explicit.  Currently, elements that wish to copy parts of other
elements walk ELEMENTS_PATH themselves and look for elements in
IMAGE_ELEMENT.  How they handle duplicate elements can differ, leading
to inconsistent behaviour.

We introduce logic in element-info to find elements in each of the
directories in ELEMENT_PATHS in *reverse* order -- that is to say,
earlier entries in the paths will overwrite later ones.

For example

 ELEMENT_PATHS=foo:bar:baz

will mean that "foo/element" will override "baz/element", since "foo"
is first.  This should be sane to anyone familiar with $PATH.
Documentation is clarified around this point and a test-case is added.

The second thing is that we want to keep the complete path of the
elements we have chosen.  We want the aforementioned elements that
walk the element list to use these canonical paths to pickup files;
this way they don't need to make local decisions about element
overrides, but can simply iterate a list and copy/merge files if they
exist.

A follow-on change (I7092e1845942f249175933d67ab121188f3511fd) will
expose this data in a separate variable that can be parsed by elements
(a further follow-on I0a64b45e9f2cfa28e84b2859d76b065a6c4590f0
modifies the elements to use this information).  Thus this does not
change the status-quo -- elements that are walking ELEMENTS_PATH
themselves and can/will continue doing that.

Change-Id: I2a29861c67de2d25c595cb35d850e92807d26ac6
2016-09-08 10:58:19 +10:00
..
caches.rst Prettify 'Caches and offline mode' documentation 2015-09-17 12:14:54 +02:00
components.rst doc: migrate from README.rst to Sphinx 2015-09-10 16:55:39 +10:00
design.rst Use fstrim to prep the block device 2016-03-13 16:24:59 +00:00
developing_elements.rst Add a best-effort sudo safety check 2016-05-09 15:41:38 +10:00
dib_lint.rst Add documentation for dib-lint 2016-05-02 01:29:17 -05:00
index.rst Add documentation for dib-lint 2016-05-02 01:29:17 -05:00
invocation.rst Making element overriding explicit 2016-09-08 10:58:19 +10:00
stable_interfaces.rst Document what our stable interfaces are 2015-07-22 09:17:02 +00:00