h6. [[Installer]] h6(. » [[Installer *Commands|*Commands]] h6((. » *Install_Merge h2. *Install_Merge h4. Use This *Command combines the entries of two obeyfiles (<code>base_file</code> and <code>changes_file</code>), placing the result in another file. h4. Syntax *Install_Merge __base_file__ __changes_file__ __dest_file__ h4. Parameters |<^{width:8em}. __base_file__|<^. the "base" source file | |<^. __changes_file__|<^. the "changes" source file | |<^. __dest_file__|<^. the destination file | h4. Notes The <code>dest_file</code> may be the same as one of the source files. The <code>changes_file</code> may optionally contain a set of rules for the positioning of new entry sections, companys or applications. These consist of any number of special one-line entries, starting |Section, |Company or |App, as appropriate. Each of these lines has the following format: <code>|[Section|Company|App] rule [rule [rule [rule ...]]]</code> <code>rule</code> is either: * <code>specifier>specifier</code> meaning create after in file * <code>specifier<specifier</code> meaning create before in file The lack of spaces is significant, and must be adhered. <code>specifier</code> is either: * case-insensitive single-word section, company or application * <code>*</code> to refer to: ** any specifier (when used on the left) ** all specifiers (when used on the right) Rules are used from the first appropriate entry in the file to the last, and left-to-right within each line. Entries from <code>changes_file</code> will be merged one by one into <code>base_file</code>. This will be achieved thus: * Scan <code>base_file</code> for the first entry with a section matching that of the new entry. If there are none, scan the command line for the first applicable rule ** If no rule applies, <code>*>*</code> defaults * Scan all consecutive entries in <code>base_file</code> with the same section for the first one with a company matching that of the new entry ** If there are none, scan the command line for the first applicable rule ** If no rule applies, <code>*>*</code> defaults * Scan all consecutive entries in <code>base_file</code> with the same section and company for the one that also matches the application in the new entry ** If there is none, scan the command line for the first applicable rule ** If no rule applies, <code>*>*</code> defaults ** If there already was such an entry, compare the version number; if the new entry is a matching or earlier version, use the entry from <code>base_file</code>, otherwise use the entry from <code>changes_file</code>. If <code>dest_file</code> is to be overwritten, it is first copied into the backup directory. Details of the operation are appended to the log file; each successful entry update is listed separately (along with new version number and any applicable old version number). h4. Examples _*Example 1:*_ The "Add to Apps" Boot window will use this command: <code>*Install_Merge <Choices$Write>.Boot.PreDesktop tempfile</code> <code><Choices$Write>.Boot.PreDesktop</code> where <code>tempfile</code> contains the line: <code>|App Configure>*</code> The section <code>ResApps</code> and company <code>Acorn</code> can be assumed to already exist (they are part of the default PreDesktop file). However, all other <code>Acorn ResApps</code> entries should come first. _*Example 2:*_ The "Run" Boot window will use this command: <code>*Install_Merge <Choices$Write>.Boot.Desktop tempfile</code> <code><Choices$Write>.Boot.Desktop</code> where <code>tempfile</code> contains the line: <code>|Section Run>Boot Run>Auto</code> The new section <code>Run</code> should be created after <code>Boot</code>, or after <code>Auto</code> ("Auto tasks") if <code>Boot</code> doesn't yet exist. Positioning of the <code>Acorn Configure</code> entry within the <code>Run</code> section is not expected to be critical. _*Example 3:*_ The nested Wimp installer, were it to be re-written to use this Installer module, would use: <code>*Install_Merge <Choices$Write>.Boot.PreDesktop changesfile</code> <code><Choices$Write>.Boot.PreDesktop</code> where <code>changesfile</code> contains the lines: <code>|Section Installation>Comments</code> <code>|Company Acorn<*</code> <code>Installation</code> may be a new section on some machines. <code>Acorn</code> should be the first company within the installation section. Since this is, at the time of writing, the first entry in <code>Acorn Installation</code>, we'll leave ordering of applications to later installers. In the event that another entry is written at a later date, which needs to be added to PreDesktop after the Wimp installation entry, a clever approach needs to be taken (because there's a chance the Wimp will be installed at a later time, and because of the default rule *>*, it would be added afterwards in PreDesktop). The new installer should first attempt to install an empty entry called <code>Acorn Wimp 0.00 Installation</code>, then install its own entry after the Wimp one. If a genuine Wimp entry already exists, the 0.00 entry is simply ignored. If the Wimp installer were only to be run later, the dummy entry's position would override the (default) <code>*>*</code> application rule in the above example. Because of this, non-empty entries must, in every case, always have version numbers of at least 0.01. h4. See also * [[*Install_DeMerge]]