150472Speter$FreeBSD$
250199Srgrimes
396856SruNote: If you modify these files, please keep hier(7) updated!
496855Sru
550199SrgrimesThese files are used to create empty file hierarchies for building the
650199Srgrimessystem into.  Some notes about working with them are placed here to try
750199Srgrimesand keep them in good working order.
850199Srgrimes
950199Srgrimes    a)  The files use 4 space indentation, and other than in the header
1050199Srgrimes        comments, should not contain any tabs.  An indentation of 4 is
1150199Srgrimes        preferable to the standard indentation of 8 because the indentation
1250199Srgrimes        of levels in these files can become quite deep causing the line to
1350199Srgrimes        overflow 80 characters.
1450199Srgrimes
1550199Srgrimes        This also matches with the files generated when using the
1650199Srgrimes        mtree -c option, which was implemented that way for the same reason.
1750199Srgrimes
1850199Srgrimes    b)  Only directories should be listed here.
1950199Srgrimes
2070923Sdougb    c)  The listing should be kept in filename sorted order.
2150199Srgrimes
2250199Srgrimes    d)  Sanity checking changes to these files can be done by following
2350203Srgrimes        this procedure (the sed -e is ugly, but fixing mtree -c to
2450199Srgrimes        not emit the trailing white space would be even uglier):
2550199Srgrimes
2650199Srgrimes            mkdir /tmp/MTREE
2750199Srgrimes            mtree -deU -f BSD.X.dist -p /tmp/MTREE
2855797Srgrimes            mtree -cdin -k uname,gname,mode -p /tmp/MTREE | \
29172421Sru		sed -e 's/ *$//' >BSD.X.new
3050199Srgrimes            diff -u BSD.X.dist BSD.X.new
3150199Srgrimes            rm -r /tmp/MTREE
3250199Srgrimes
3350199Srgrimes        Note that you will get some differences about /set lines,
3450199Srgrimes        and uname= gname= on certain directory areas, mainly man page
3550199Srgrimes        sections.  This is caused by mtree not having a look ahead
3650199Srgrimes        mechanism for making better selections for these as it
3750199Srgrimes        traverses the hierarchy.
3850199Srgrimes
39217596Suqs        The BSD.X.new file should NOT be committed, as it will be missing
40217596Suqs        the correct header, and important keywords like ``nochange''.
41217596Suqs        Simply use the diff for a sanity check to make sure things are in
42217596Suqs        the correct order and correctly indented.
4350199Srgrimes
4450199Srgrimes    e)  Further sanity checking of the system builds with DESTDIR=/someplace
4550199Srgrimes        are more complicated, but can often catch missing entries in these
4650199Srgrimes        files.  I tend to run this more complete sanity check shortly after
4750199Srgrimes        the target date for a new release is announced.
4850199Srgrimes
4950199Srgrimes        If you want details on it bug me about it via email to
5050199Srgrimes        rgrimes@FreeBSD.org.
51