[src/trunk]: src/doc Document build.sh "live-image" and "install-image" targets.

[apb <apb%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/add5470a95bb
branches:  trunk
changeset: 773738:add5470a95bb
user:      apb <apb%NetBSD.org@localhost>
date:      Tue Feb 14 21:19:19 2012 +0000

description:
Document build.sh "live-image" and "install-image" targets.

These were documented in revision 1.97 of src/BUILDING, but were
not documented in src/doc/BUILDING.sh.  The original log message
was:

revision 1.97
date: 2012/01/22 03:53:32;  author: tsutsui;  state: Exp;  lines: +39 -0
Add "live-image" and "install-image" target support to build.sh.

"live-image" target builds pre-installed disk images that can be used on
emulators or boot from USB memory sticks to try NetBSD without installation.
Currently amd64, i386, pmax, sparc, sparc64, sun2, sun3, and vax
(which have working emulators and don't require extra tools like preparing
 msdosfs or partitioning MD label structures) support this target.

"install-image" target builds an bootable installation disk image that can
be used as an install CD but burned into USB memory sticks etc.
Current only amd64 and i386 (which would support USB boot) have this target.

For more details (and known issue) see following posts on netbsd-bugs@:
http://mail-index.NetBSD.org/netbsd-bugs/2011/08/06/msg023639.html
http://mail-index.NetBSD.org/netbsd-bugs/2011/09/23/msg024207.html
http://mail-index.NetBSD.org/netbsd-bugs/2011/12/07/msg025166.html
http://mail-index.NetBSD.org/netbsd-bugs/2011/12/08/msg025178.html

No particular comments about implementation, and
"go ahead" comments from mrg@, riz@ and christos@.

Closes PR toolchain/45153 and PR misc/45155.

diffstat:

 doc/BUILDING.mdoc |  72 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 71 insertions(+), 1 deletions(-)

diffs (93 lines):

diff -r f54aa9dfd776 -r add5470a95bb doc/BUILDING.mdoc
--- a/doc/BUILDING.mdoc Tue Feb 14 19:39:37 2012 +0000
+++ b/doc/BUILDING.mdoc Tue Feb 14 21:19:19 2012 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: BUILDING.mdoc,v 1.85 2011/09/09 18:48:34 apb Exp $
+.\"    $NetBSD: BUILDING.mdoc,v 1.86 2012/02/14 21:19:19 apb Exp $
 .\"
 .\" Copyright (c) 2001-2011 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -1153,6 +1153,68 @@
 but which can be installed from
 .Pa pkgsrc/sysutils/cdrtools .
 .
+.It Sy install-image
+Create a bootable
+.Nx
+installation disk image in the
+.Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /installation/installimage
+directory.
+The bootable installation disk image is
+suitable to USB flash memory sticks etc. for machines which
+may support boot from such USB devices.
+File system in the bootable disk image will have a layout
+as described in
+.Xr release 7 .
+.Pp
+The installation image is bootable, and will automatically
+run the
+.Xr sysinst 8
+menu-based installation program, which can be used to install or upgrade a
+.Nx
+system.
+Bootable installation images also contain tools that may be
+useful in repairing a damaged
+.Nx
+installation.
+.Pp
+Before
+.Dq make install-image
+is attempted, RELEASEDIR must be populated by
+.Dq make release
+or equivalent
+and RELEASEDIR binaries must be built with
+.Sy MKUNPRIVED=yes
+to refer permission information from specfiles.
+.
+.It live-image
+Create
+.Nx
+live images in the
+.Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /installation/liveimage
+directory.
+The live image contains all necessary files
+to boot
+.Nx
+upto multi user mode, including all files
+which should be extracted during installation,
+.Nx
+disklabel, and bootloaders etc.
+.Pp
+The live image is suitable for misc emulators like QEMU,
+and also usuful to try
+.Nx
+on real machines with USB
+flash memory sticks without installation.
+.Pp
+Before
+.Dq make live-image
+is attempted, RELEASEDIR must be populated by
+.Dq make release
+or equivalent
+and RELEASEDIR binaries must be built with
+.Sy MKUNPRIVED=yes
+to refer permission information from specfiles.
+.
 .It Sy regression-tests
 Can only be run after building the regression tests in the directory
 .Dq regress .
@@ -1388,6 +1450,14 @@
 Perform
 .Dq make iso-image-source .
 .
+.It Sy install-image
+Perform
+.Dq make install-image .
+.
+.It Sy live-image
+Perform
+.Dq make live-image .
+.
 .El
 .
 .Pp