Differential D27848 Diff 82223 en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml

Changeset View

Standalone View

en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml

Show First 20 Lines • Show All 1,189 Lines • ▼ Show 20 Lines <step>

<title>Update and Build</title> <title>Update and Build</title>

<screen>&prompt.root; <userinput>svnlite update /usr/src</userinput> <co xml:id="updating-src-qs-svnup"/> <screen>&prompt.root; <userinput>svnlite update /usr/src</userinput> <co xml:id="updating-src-qs-svnup"/>

<emphasis>check <filename>/usr/src/UPDATING</filename></emphasis> <co xml:id="updating-src-qs-review-updating"/> <emphasis>check <filename>/usr/src/UPDATING</filename></emphasis> <co xml:id="updating-src-qs-review-updating"/>

&prompt.root; <userinput>cd /usr/src</userinput> <co xml:id="updating-src-qs-cd"/> &prompt.root; <userinput>cd /usr/src</userinput> <co xml:id="updating-src-qs-cd"/>

&prompt.root; <userinput>make -j<replaceable>4</replaceable> buildworld</userinput> <co xml:id="updating-src-qs-buildworld"/> &prompt.root; <userinput>make -j<replaceable>4</replaceable> buildworld</userinput> <co xml:id="updating-src-qs-buildworld"/>

&prompt.root; <userinput>make -j<replaceable>4</replaceable> kernel</userinput> <co xml:id="updating-src-qs-kernel"/> &prompt.root; <userinput>make -j<replaceable>4</replaceable> kernel</userinput> <co xml:id="updating-src-qs-kernel"/>

&prompt.root; <userinput>shutdown -r now</userinput> <co xml:id="updating-src-qs-reboot"/> &prompt.root; <userinput>shutdown -r now</userinput> <co xml:id="updating-src-qs-reboot"/>

&prompt.root; <userinput>etcupdate -p</userinput> <co xml:id="updating-src-qs-etcupdate-preworld"/>

ngieUnsubmitted

Done

nit: this indentation seems off.

ngie: nit: this indentation seems off.

driesmAuthorUnsubmitted

Done

Indeed!

driesm: Indeed!

&prompt.root; <userinput>cd /usr/src</userinput> <co xml:id="updating-src-qs-cd2"/> &prompt.root; <userinput>cd /usr/src</userinput> <co xml:id="updating-src-qs-cd2"/>

&prompt.root; <userinput>make installworld</userinput> <co xml:id="updating-src-qs-installworld"/> &prompt.root; <userinput>make installworld</userinput> <co xml:id="updating-src-qs-installworld"/>

&prompt.root; <userinput>mergemaster -Ui</userinput> <co xml:id="updating-src-qs-mergemaster"/> &prompt.root; <userinput>etcupdate -B</userinput> <co xml:id="updating-src-qs-etcupdate"/>

jhbUnsubmitted

Done

etcupdate -B here is actually a bit quicker as it uses the files from the built world to populate the temp root. (It is a no-op for -p)

I don't actually use -F in practice myself, but it's fine to recommend it by default. It will soon cease to matter since git doesn't update the strings anyway.

jhb: `etcupdate -B` here is actually a bit quicker as it uses the files from the built world to…

driesmAuthorUnsubmitted

Done

I was doubting myself to recommend -F or not given the tags wont remain, in the end I left it out.

driesm: I was doubting myself to recommend -F or not given the tags wont remain, in the end I left it…

&prompt.root; <userinput>shutdown -r now</userinput> <co xml:id="updating-src-qs-shutdown"/></screen> &prompt.root; <userinput>shutdown -r now</userinput> <co xml:id="updating-src-qs-shutdown"/></screen>

<para>Get the latest version of the source. See <para>Get the latest version of the source. See

<xref linkend="updating-src-obtaining-src"/> for <xref linkend="updating-src-obtaining-src"/> for

more information on obtaining and updating more information on obtaining and updating

source.</para> source.</para>

</callout> </callout>

<para>Check <filename>/usr/src/UPDATING</filename> <para>Check <filename>/usr/src/UPDATING</filename>

for any manual steps required before or after building for any manual steps required before or after building

from source.</para> from source.</para>

</callout> </callout>

<para>Update and merge configuration files in

<filename>/etc/</filename> required before

installworld.</para>

</callout>

<para>Go to the source directory.</para> <para>Go to the source directory.</para>

</callout> </callout>

<para>Compile the world, everything except the <para>Compile the world, everything except the

kernel.</para> kernel.</para>

</callout> </callout>

Show All 11 Lines equivalent to <command>make buildkernel

<para>Go to the source directory.</para> <para>Go to the source directory.</para>

</callout> </callout>

<para>Install the world.</para> <para>Install the world.</para>

</callout> </callout>

<para>Update and merge configuration files in <para>Update and merge configuration files in

</callout> </callout>

<para>Restart the system to use the newly-built world <para>Restart the system to use the newly-built world

and kernel.</para> and kernel.</para>

</callout> </callout>

▲ Show 20 Lines • Show All 278 Lines • ▼ Show 20 Lines &prompt.root; <userinput>shutdown -r now</userinput></screen>

<title>Completing the Update</title> <title>Completing the Update</title>

<para>A few final tasks complete the update. Any modified <para>A few final tasks complete the update. Any modified

configuration files are merged with the new versions, outdated configuration files are merged with the new versions, outdated

libraries are located and removed, then the system is libraries are located and removed, then the system is

restarted.</para> restarted.</para>

<title>Merging Configuration Files with <title>Merging Configuration Files with

&man.etcupdate.8;</title>

<para>&man.etcupdate.8; is a tool for managing updates to

files that are not updated as part of an installworld such

as files in <filename>/etc/</filename>. It manages updates

by doing a three-way merge of changes made to these files

against the local versions. It is also designed to minimize

the amount of user intervention, in contrast to

&man.mergemaster.8;'s interactive prompts.</para>

ngieUnsubmitted

Done

against the local versions. It is also designed to minimize

- the amount of user intervention which is the largest benefit

- in comparison to &man.mergemaster.8;.</para>

+ the amount of user intervention, in contrast to

+ &man.mergemaster.8;'s interactive prompts.</para>

<note>

ngie:

<note>

<para>In general, &man.etcupdate.8; does not need any

specific arguments for its job. There is however a handy

in between command for sanity checking what will be done

the first time &man.etcupdate.8; is used:

<screen>&prompt.root; <userinput>etcupdate diff</userinput></screen>

This command allows the user to audit configuration

changes.</para>

ngieUnsubmitted

Not Done

<screen>&prompt.root; <userinput>etcupdate diff</userinput></screen>

- By giving the output a quick look and making sure the diff

- looks OK, the merge should work just fine.</para>

+ <userinput>etcupdate diff</userinput> allows the end-user to audit

+ configuration changes.</para>

</note>

This wording seems a bit indirect.

end-user might need to be replaced with something that matches other surrounding descriptions.

ngie: This wording seems a bit indirect. `end-user` might need to be replaced with something that…

</note>

<para>If &man.etcupdate.8; is not able to merge a file

automatically, the merge conflicts can be resolved with

manual interaction by issuing:</para>

<screen>&prompt.root; <userinput>etcupdate resolve</userinput></screen>

<para>When switching from &man.mergemaster.8; to

&man.etcupdate.8; the first run might print some bogus

conflicts due to already applied changes. In general, the

following command sequence should recover from this

behavior:</para>

<step>

<title>Bootstrapping &man.etcupdate.8;</title>

<screen>&prompt.root; <userinput>etcupdate diff</userinput> <co xml:id="updating-src-completing-merge-diff"/>

&prompt.root; <userinput>etcupdate bootstrap</userinput> <co xml:id="updating-src-completing-merge-bootstrap"/>

&prompt.root; <userinput>etcupdate diff</userinput> <co xml:id="updating-src-completing-merge-diff-after"/></screen>

<para>Check the output before updating sources and

building the new world. If the output shows a lot

of diffs that are not expected, continue with the

bootstrap command.</para>

</callout>

<para>Bootstrap the program, for more information

see &man.etcupdate.8;.</para>

</callout>

<para>Check the diff again after bootstrapping. The

unexpected diffs should be gone.</para>

</callout>

</calloutlist>

</step>

</procedure>

</warning>

</sect3>

<title>Merging Configuration Files with

&man.mergemaster.8;</title> &man.mergemaster.8;</title>

<para>&man.mergemaster.8; provides an easy <para>&man.mergemaster.8; provides a way to merge changes that

way to merge changes that have been made to system have been made to system configuration files with new

configuration files with new versions of those files.</para> versions of those files. &man.mergemaster.8; is an

jhbUnsubmitted

Done

s/more preferred/preferred/. Another way to frame it may be that mergemaster is an older tool and legacy installs may still need to use it to keep up to date.

In general with etcupdate it would be nice to have a warning or headsup somewhere that running 'etcupdate diff' and making sure the diff looks ok is good before using it for the first time. If the diff shows a lot of unexpected changes then etcupdate may do surprising things. Also, if you start using etcupdate on a system that has been managed via mergemaster, the first run of etcupdate may report some bogus conflicts due to already-applied changes. It might be good to add a section about switching from one scheme to the other somewhere. In general what you would want to do in that case is:

run 'etcupdate diff' _before_ updating your sources and building the new world + kernel. If it shows lots of diffs you don't expect, then run 'etcupdate bootstrap' and compare 'etcupdate diff' again. Any diffs should now be real changes compared to the stock files. If necessary, manually update files in /etc to remove undesired local changes. Then proceed to update the source tree and build world, etc.

jhb: s/more preferred/preferred/. Another way to frame it may be that mergemaster is an older tool…

driesmAuthorUnsubmitted

Done

Added a note to use "etcupdate diff" as a go to before running the actual command. Also added a warning regarding the first use of etcupdate and the bogus conflicts.

driesm: Added a note to use "etcupdate diff" as a go to before running the actual command. Also added a…

alternative to the preferred &man.etcupdate.8; tool.</para>

<para>With <option>-Ui</option>, &man.mergemaster.8; <para>With <option>-Ui</option>, &man.mergemaster.8;

ngieUnsubmitted

Done

versions of those files. &man.mergemaster.8; is an

- alternative to the preferred &man.etcupdate.8; tool,

- although &man.mergemaster.8; might still be needed on legacy

+ alternative to the preferred &man.etcupdate.8; tool.

+ &man.mergemaster.8; might still be needed on legacy

installs.</para>

<para>With <option>-Ui</option>, &man.mergemaster.8;

These seem like 2 separate thoughts that should be separate sentences.

ngie: These seem like 2 separate thoughts that should be separate sentences.

driesmAuthorUnsubmitted

Done

I was actually doubting if we should still mention that: "mergemaster might be needed for older systems". In this revision I left it out as it comes over a bit undecided. If we would like to deprecate mergemaster and remove it from base at one point in time a comment like that isn't very helpful for that plan. From my point of view all supported releases can be updated with etcupdate.

driesm: I was actually doubting if we should still mention that: "mergemaster might be needed for older…

automatically updates files that have not been user-modified automatically updates files that have not been user-modified

and installs new files that are not already present:</para> and installs new files that are not already present:</para>

<screen>&prompt.root; <userinput>mergemaster -Ui</userinput></screen> <screen>&prompt.root; <userinput>mergemaster -Ui</userinput></screen>

<para>If a file must be manually merged, an interactive <para>If a file must be manually merged, an interactive

display allows the user to choose which portions of the display allows the user to choose which portions of the

files are kept. See &man.mergemaster.8; for more files are kept. See &man.mergemaster.8; for more

▲ Show 20 Lines • Show All 146 Lines • Show Last 20 Lines