Index: lists.html =================================================================== --- lists.html (revision 2109) +++ lists.html (revision 2110) @@ -22,4 +22,104 @@ In practice this means the user can replace, prepend or append ordered lists from various sources. A common example is setting the library search paths. -TODO: EXAMPLES +

examples

+ +

simple overwrite

+Config sources (ordered by priority): + +
role priority policy content +
system 200 overwrite A,B,C +
user 400 overwrite (not defined) +
project 600 overwrite D,E +
+

Merge iterations: + +
step description output list after executing this step remarks +
0. reset the output (empty)   +
1. apply system A,B,C   +
2. apply user A,B,C "not defined" doesn't mean "empty", so the list is not deleted - no change +
3. apply project D,E replace the original output because of the overwrite policy +
+

Situation: the project is restricted to local footprint libs; this setup +makes sure no system or user configuration injects external footprint paths. + +

empty overwrite

+Config sources (ordered by priority): + +
role priority policy content +
system 200 overwrite A,B,C +
user 400 overwrite (not defined) +
project 600 overwrite defined to be an empty list +
+

Merge iterations: + +
step description output list after executing this step remarks +
0. reset the output (empty)   +
1. apply system A,B,C   +
2. apply user A,B,C "not defined" doesn't mean "empty", so the list is not deleted - no change +
3. apply project (empty) replace the original output because of the overwrite policy +
+ +

prepend

+Config sources (ordered by priority): + +
role priority policy content +
system 200 overwrite A,B,C +
user 400 prepend (not defined) +
project 600 prepend D,E +
+

Merge iterations: + +
step description output list after executing this step remarks +
0. reset the output (empty)   +
1. apply system A,B,C   +
2. apply user A,B,C "not defined" doesn't mean "empty", so the list is not deleted - no change +
3. apply project D,E,A,B,C   +
+

Situation: the project has its own footprint libs with two paths; these +should be searched before system and user paths, still, system path is also +kept so stock footprints can be found. +

+This is better than hardwiring A,B,C in the project's list: A, B and C may +depend on the installation on a given system. A project file has no idea +about how the system is installed but it is assumed system installation +and the system configuration file are consistent. + +

append

+Config sources (ordered by priority): + +
role priority policy content +
system 200 overwrite A,B,C +
user 400 append (not defined) +
project 600 append D,E +
+

Merge iterations: + +
step description output list after executing this step remarks +
0. reset the output (empty)   +
1. apply system A,B,C   +
2. apply user A,B,C "not defined" doesn't mean "empty", so the list is not deleted - no change +
3. apply project A,B,C,D,E   +
+

Situation: the project has its own footprint libs with two paths; these +should be searched after system and user paths. This means the local footprint +lib has lower priority than the stock footprints. See system-dependent +installation remarks in the previous point. + + +

prepend+append

+Config sources (ordered by priority): + +
role priority policy content +
system 200 overwrite A,B,C +
user 400 prepend X,Y,Z +
project 600 append D,E +
+

Merge iterations: + +
step description output list after executing this step remarks +
0. reset the output (empty)   +
1. apply system A,B,C   +
2. apply user X,Y,Z,A,B,C   +
3. apply project X,Y,Z,A,B,C,D,E   +