Home | History | Annotate | Line # | Download | only in src
UPDATING revision 1.122
      1 $NetBSD: UPDATING,v 1.122 2004/05/31 00:18:58 itojun Exp $
      2 
      3 This file is intended to be a brief introduction to the build
      4 process and a reference on what to do if something doesn't work.
      5 
      6 For a more detailed description see Makefile.
      7 
      8 Recent changes:
      9 ^^^^^^^^^^^^^^^
     10 
     11 20040516:
     12 	The end-user modifiable X11 configuration has been moved
     13 	from /usr/X11R6/lib/X11/<dir> to /etc/X11/<dir>.
     14 	Ensure that src and xsrc is up to date, and run
     15 	"make cleandir" in src/x11 before your next build.
     16 
     17 20040426:
     18 	Support for the original dynamic sysctl node structure has
     19 	been removed in favor of the newer layout.  This affects
     20 	consumers of the create and delete interface, as well as
     21 	the dynamic discovery mechanism.  This is believed only to
     22 	be the sysctl(8) binary itself, at this point in time, so
     23 	the only effect of this should be that a sysctl binary
     24 	built from sources dated between 2003/12/04 and 2004/03/24
     25 	will not work on a kernel built from sources dated after
     26 	2004/04/25.  If you need a new sysctl binary but build.sh
     27 	does not work, make sure that your revision of
     28 	src/sys/sys/sysctl.h is 1.112 (or later), and then the
     29 	do the following:
     30 
     31 	cd /usr/src (or wherever your source tree is)
     32 	make USETOOLS=no includes
     33 	cd lib/libc
     34 	make USETOOLS=no dependall install
     35 	cd ../../sbin/sysctl
     36 	make USETOOLS=no dependall install
     37 
     38 	If you are using older sysctl binary, GNU autoconf would fail to
     39 	identify your machine architecture, and tries to build binary for
     40 	"unknown-unknown-netbsd20F" or something like that.  if that happens,
     41 	make sure to follow the above steps.
     42 
     43 20040425:
     44 	The ffs superblock issues listed below under 20040109 and 20030402
     45 	are now automatically addressed by the /etc/rc.d/fixsb script or by
     46 	sysinst when it checks a a filesystem. The manual fsck_ffs -b16 -c4
     47 	invocation mentioned below will continue to work and is now
     48 	automated by those scripts.  Note that under certain circumstances,
     49 	affected filesystems upgraded to a -current kernel first before
     50 	upgrading their userland with the fixsb and fsck_ffs fixes may
     51 	encounter a 'freeing free inode' panic when writing to the affected
     52 	filesystem, so it is a good idea to repair the filesystem as soon as
     53 	possible.  For more details on the fixsb script, see pr install/25138.
     54 
     55 20040418:
     56 	statfs(2) and friends have been replaced with statvfs(2). Before
     57 	installing a newly build userland make sure that you are running
     58 	a newly built kernel with COMPAT_20 set. In addition your libc
     59 	build might not work (undefined SYS_statfs symbol) because make
     60 	clean does not know how to remove files it does not know about
     61 	anymore. Manually remove all generated .S sources and objects
     62 	from the libc build directory.
     63 
     64 20040326:
     65 	The method by which athhal-elf.o gets pulled into i386 kernel builds
     66 	has been changed. The file is now stored as a uuencoded file in CVS
     67 	and the generated Makefile will use the new .uue rules from bsd.file.mk
     68 	to build it.
     69 
     70 	This means you must have the latest bsd.files.mk installed when
     71 	building a kernel without USETOOLS=yes.
     72 
     73 20040318:
     74 	A bug in the cgd(4) blowfish code was corrected, without
     75 	provision of backwards compatibility, after several public
     76 	notices over several months. Users of cgd with blowfish cipher
     77 	ONLY must dump their data before updating their kernels, and
     78 	recreate cgd's and restore data using the new kernel. See
     79 	(recent message to current-users, URL when mail-index has updated)
     80 
     81 20040313:
     82 	On acorn32, the opms and qms drivers have been withdrawn, and
     83 	the old wsqms driver is now called qms.  Kernel config files
     84 	will need updating.  See the ones in sys/arch/acorn32/conf
     85 	for examples.
     86 
     87 20040125:
     88 	On acorn32, the beep and sysbeep devices are no longer
     89 	needed, and will need to be deleted from kernel configuration
     90 	files.
     91 
     92 20040109:
     93 	Compatibility for old ffs superblock layouts has been
     94 	added, and the restrictive fsck checks have been reenabled
     95 	when using those layouts.  If you have been using -current
     96 	since 20030402, you may find that fsck again signals fatal
     97 	superblock mismatches.  To repair, make sure you have
     98 	an updated fsck_ffs and then you can use fsck_ffs -b 16 -c 4
     99 	to complete the filesystem upgrade.  A message has
    100 	been added to the kernel which should detect this problem.
    101 	See the following discussion for more information:
    102 	http://mail-index.NetBSD.org/current-users/2004/01/11/0022.html
    103 
    104 20031203:
    105 	New binutils builds may fail due to old dependencies.
    106 	It's necessary to "make cleandir" to ensure that
    107 	the dependencies will be rebuilt correctly.
    108 
    109 20031111:
    110 	A newer mkdep is needed.  Error noting that is
    111 		cc: Ambiguous abbreviation --
    112 
    113 20031008:
    114 	/usr/include/sys/disklabel_mbr.h was removed.
    115 	It's necessary to "make cleandir" to ensure that
    116 	the dependencies will be rebuilt correctly.
    117 
    118 20031007:
    119 	A sign exension bug was fixed which set all the high bits
    120 	of our newly expanded ffs fs_flags.  This should only
    121 	affect users who installed or upgraded in September of 2003.
    122 	A small utility program was posted to tech-kern which
    123 	should fix this problem, and a warning message was added
    124 	to the kernel which should discover and warn about it.  See
    125 	http://mail-index.NetBSD.org/tech-kern/2003/10/07/0005.html
    126 
    127 20030906:
    128 	With the addition of siginfo support the old signal trampoline
    129 	code has been deprecated to COMPAT_16. Make sure that your running
    130 	kernel has COMPAT_16 enabled before building userland.
    131 
    132 20030801:
    133 	With the new openssl, there is some header and library shuffling.
    134 	rm -f /usr/include/des.h /usr/include/kerberosIV/* /lib/libdes* \
    135 	/usr/lib/libdes* before building.
    136 
    137 20030703:
    138 	Texinfo was updated to 4.6.  To avoid failures when trying to
    139 	build the included texinfo files, do:
    140 
    141 	cd src/gnu/usr.bin/texinfo
    142 	make MKINFO=no dependall install
    143 
    144 20030630:
    145 	Groff was updated to 1.19; it's probably necessary to do
    146 		cd share/mk && make install
    147 		cd src/gnu/usr.bin/groff
    148 		make MKMAN=no dependall install
    149 	(untested).
    150 
    151 20030516:
    152 	Due to bugs in the export handling code, invalid export lines
    153 	were accepted before and caused the kernel to panic when
    154 	mountd got restarted because it freed memory that had already
    155 	been freed. This has been fixed and the kernel checks
    156 	export addresses very strictly. If you upgrade your kernel,
    157 	make sure you also upgrade mountd, because if your export
    158 	file contains lines with an old inet4 address syntax (i.e.
    159 	a.b.c or a.b or a), they will get rejected by the new kernel.
    160 
    161 20030402:
    162 	The superblock layout for FFS was changed.  If you have 1.6
    163 	fsck binaries, they will signal a fatal superblock mismatch
    164 	with the first alternate, because they compare too many
    165 	fields (even ones that aren't useful).  If possible, upgrade
    166 	your fsck_ffs binary before using a new kernel.
    167 	None of this signals actual filesystem damage.
    168 
    169 20030324:
    170 	sendmail version 8.12.8 was imported.  Since sendmail is
    171 	now setgid to the smmsp group, and runs in "collection"
    172 	mode for most common activities, there is a new config
    173 	file called submit.cf that needs to live in /etc/mail.
    174 	The generic submit.cf sample in /usr/share/sendmail/cf
    175 	is named netbsd-msp.cf.  Upgrading your regular sendmail
    176 	configuration file is also strongly advised.
    177 
    178 	See the section named "MESSAGE SUBMISSION PROGRAM" in
    179 	the updated /usr/share/sendmail/README file for more
    180 	information.
    181 
    182 20030117:
    183 	Texinfo was updated to 4.3.  To avoid failures when trying to
    184 	build the included texinfo files, do:
    185 
    186 	cd src/gnu/usr.bin/texinfo
    187 	make MKINFO=no dependall install
    188 
    189 20021223:
    190 	The METALOG format changed slightly, to remove the leading
    191 	"${DESTDIR}" from path names.
    192 	This only affects people building with UNPRIVED.
    193 	For complete safety, remove the DESTDIR entirely and
    194 	update tools/mtree, before running make build.
    195 
    196 20021219:
    197 	CVS repository layout was changed.  See the following for details
    198 	if you are using (anonymous) cvs to update your tree.
    199 
    200 	http://mail-index.NetBSD.org/netbsd-announce/2002/12/19/0000.html
    201 
    202 20021219:
    203 	install(1) had a '-N dbdir' option added, to specify an
    204 	alternate location to look up users & groups (instead
    205 	of the host system passwd(5) and group(5) databases).
    206 
    207 	The build system was modified to take advantage of
    208 	this option (using ${NETBSDSRCDIR}/etc), so if you
    209 	use USETOOLS==no, you may have to rebuild and
    210 	reinstall usr.bin/xinstall first.
    211 
    212 20021130:
    213 	fparseln(3) moved from libutil to libc.
    214 	If building to DESTDIR=/, reinstall the includes
    215 	and rebuild libc:
    216 		make includes
    217 		make do-lib-libc
    218 	If using build.sh, "cd tools/compat && make clean"
    219 	before rebuilding the tools.
    220 
    221 20021126:
    222 	The mk.conf(5) variable SYS_INCLUDE has been deprecated,
    223 	including the optional "SYS_INCLUDE=symlinks" support.
    224 	All header files, including <sys/*.h> are copied into
    225 	/usr/include.
    226 
    227 20021121:
    228 	The C run-time support files crtbegin.o and crtend.o
    229 	(and their companions crtbeginS.o and crtendS.o) were
    230 	split up, with new crti.o and crtn.o files resulting.
    231 	This means that libtool needs to be rebuilt once the
    232 	new libraries are installed.  The process of rebuilding
    233 	libtool will cause it to automatically notice the new
    234 	required files, but it *must* be rebuilt in order to
    235 	do this.
    236 
    237 	An out-of-date libtool will result in shared libraries
    238 	which lack _init() and _fini() routines, which means that
    239 	their global contructors/destructors will not be invoked.
    240 
    241 20021121:
    242 	A bug related to how ARM ELF objects were tagged has been
    243 	corrected.
    244 
    245 	NetBSD ARM ELF uses the soft-VFP floating point model by
    246 	default.  However, the assembler lacked support for marking
    247 	objects as using the VFP floating point format, and the
    248 	compiler was not properly passing the flag indicating "soft-VFP"
    249 	to the assembler.
    250 
    251 	Unfortunately, this means that the linker will now consider
    252 	old (i.e. not marked "softvfp") NetBSD ARM ELF objects to be
    253 	incompatible with new (properly marked) objects.
    254 
    255 	The problem will only manifest itself if you attempt to compile
    256 	a new program using the fixed toolchain, and link that program
    257 	against old libraries which do not have the proper "softvfp"
    258 	markings.  ALL OF YOUR EXISTING BINARIES AND SHARED LIBRARIES
    259 	WILL CONTINUE TO WORK PROPERLY.
    260 
    261 	The only work-around for the problem is to recompile all of
    262 	the libraries on the system.  The easiest way to do this for
    263 	system libraries is to install a binary snapshot; they are
    264 	generally available on releng.NetBSD.org.  Any packages you
    265 	have installed which supply libraries will have to be recompiled
    266 	if you wish to link new programs against those libraries.
    267 
    268 	If you have questions about this matter, please contact
    269 	port-arm (a] NetBSD.org.
    270 
    271 20021011:
    272 	Systrace has been improved to support privilege elevation.
    273 	Updating the kernel requires the userland part of systrace
    274 	to be rebuilt.
    275 
    276 20021010:
    277 	The config(8) grammar was changed to allow options to register
    278 	dependencies on attributes, as well as other options.  Users
    279 	must update and reinstall usr.sbin/config before building a new
    280 	kernel.
    281 
    282 20021009:
    283 	A new attribute dependency syntax was introduced to config(8),
    284 	which is now used by the SCSI configuration description.  Users
    285 	must update and reinstall usr.sbin/config before building a new
    286 	kernel.
    287 
    288 20021003:
    289 	Several changes have been made to the autoconfiguration
    290 	framework.  Users must update and reinstall usr.sbin/config
    291 	before building a new kernel.
    292 
    293 20021001:
    294 	The i386mp branch has been merged.  To compile a kernel, users
    295 	will need to add the option 'cpu* at mainbus?' to their configuration
    296 	file.  Multiprocessor kernels will need
    297 	ioapic*		at mainbus? apid ?
    298 	options		MULTIPROCESSOR
    299 	options		COM_MPLOCK
    300 
    301 20020922:
    302 	MKDYNAMICROOT=yes enabled by default, which means that
    303 	certain shared libraries are installed into /lib, the shared
    304 	linker is installed into /libexec, and all programs in /bin
    305 	and /sbin are dynamically linked.
    306 	If you do not use "make build", you should ensure that
    307 	you have the libraries and shared linker in the new locations,
    308 	with:
    309 		make do-lib-csu do-lib-libc do-lib do-gnu-lib do-ld.elf_so
    310 
    311 20020917:
    312 	USE_NEW_TOOLCHAIN has been replaced with:
    313 	    -	TOOLCHAIN_MISSING -- set to "yes" on platforms for which
    314 		there is no working in-tree toolchain (hppa, ns32k, sh5,
    315 		x86_64).
    316 	    -	EXTERNAL_TOOLCHAIN -- if defined by the user, points to the
    317 		root of an external toolchain (e.g. /usr/local/gnu).  This
    318 		enables the cross-build framework even for TOOLCHAIN_MISSING
    319 		platforms.
    320 
    321 20020906:
    322 	gehenna-devsw has been merged into the trunk. Need to update and
    323 	reinstall usr.sbin/config before building the kernel.
    324 
    325 20020822:
    326 	Crunched rescue tools (contents of /bin and /sbin, plus others)
    327 	are now provided in /rescue.
    328 
    329 	To ensure that these are built statically linked (no matter
    330 	what the setting of LDSTATIC is), use a crunchgen(1) built
    331 	from sources newer than 20020820 (see the next entry).
    332 
    333 20020820:
    334 	crunchgen(1) changed to ensure that the generated program
    335 	is statically linked.
    336 
    337 	Solution: update and reinstall usr.bin/crunch
    338 
    339 20020605:
    340 	smmsp user/group has been added for sendmail.
    341 
    342 	Add the following into /etc/group:
    343 
    344 	smmsp:*:17:
    345 
    346 	and the following to /etc/master.passwd (via vipw):
    347 
    348 	smmsp:*:17:17::0:0:Sendmail Message Submission Program:/nonexistent:/sbin/nologin
    349 
    350 20020515:
    351 	sshd user/group has been added.  Need to hand add this in, or sshd
    352 	will not let you log in (with default, or UsePrivlegeSeparation=yes)
    353 
    354 	Add the following into /etc/group:
    355 
    356 	sshd:*:16:
    357 
    358 	and the following to /etc/master.passwd (via vipw):
    359 
    360 	sshd:*:16:16::0:0:& pseudo-user:/var/chroot/sshd:/sbin/nologin
    361 	
    362 	Also /var/chroot/sshd directory needs to be present (digged as part of
    363 	the build process).
    364 
    365 20020426:
    366 	NBUILDJOBS obsoleted in favor of just using -j.
    367 
    368 20020426:
    369 	etc/postinstall added, which performs various checks for 
    370 	configuration file updates and changes, and can fix most of
    371 	the problems identified.
    372 	This should make it much easier to upgrade a system's
    373 	configuration from earlier systems (as far back as NetBSD 1.5).
    374 
    375 20020320:
    376 	<bsd.lib.mk> needs a new install(1) for its "-a cmd" support.
    377 	Build and install at usr.bin/xinstall before the build.
    378 
    379 20020319:
    380 	Raw IPv6 socket now makes strict checking for sa_family and sa_len
    381 	on send(2) operation.  Be sure to have sbin/rtsol and usr.sbin/rtsold
    382 	newer than November 2001 when you upgrade the kernel.
    383 
    384 20020311:
    385 	ssh configuration files were moved from /etc to /etc/ssh.  Beware
    386 	if you restart your machine from remote.  Note that sshd.conf needs
    387 	to be changed (due to the use of "/etc" inside).
    388 
    389 20020223:
    390 	Users of the VAX port will need to rebuild and install gas
    391 	so it deal with the now present register prefix used in all
    392 	the VAX assembly files.
    393 
    394 20020118:
    395 	ntpd user/group has been added.  Need to hand add this in or builds
    396 	will break as mtree aborts early.
    397 
    398 	Add the following into /etc/group:
    399 
    400 	ntpd:*:15:
    401 
    402 	and the following to /etc/master.passwd (via vipw):
    403 
    404 	ntpd:*:15:15::0:0:Ntpd pseudo-user:/var/chroot/ntpd:/sbin/nologin
    405 
    406 20011207:
    407 	If you're attempting to build a snapshot on sparc64 and are getting
    408 	reloc errors from the toolchain groff binary this means your native
    409 	toolchain has some broken C++ bits.
    410 
    411 	To fix:
    412 
    413 	Build a new toolchain (i.e. build.sh -t)
    414 	Use the new toolchain to build and install natively (i.e. /usr/lib)
    415 
    416 	gnu/lib/libgcc
    417 	gnu/lib/libstdc++
    418 
    419 	After this a snapshot will be able to be built.
    420 
    421 20011201:
    422 	In order for a sparc64 build to work you must have a working awk. If
    423 	you've built and installed a system with the new toolchain up to this
    424 	point you do not have a working awk as its ability to do floating
    425 	point is broken. 
    426 
    427 	To build:
    428 
    429 	remake and install gnu/lib/libgcc
    430 	remake and install gnu/usr.bin/gawk into /usr/bin (make sure it links
    431 	against the new libgcc.a)
    432 
    433 20011128:
    434 	Kernel config information was changed to use defflag in
    435 	the various "files" files.  Bug fixes to config(8) are
    436 	required in order for this to work properly.  Make sure
    437 	to build and install in usr.sbin/config before attempting
    438 	to build a new kernel.
    439 
    440 20011030:
    441 	libc/locale/wcstod.c now needs new lint(1). Update lint(1)
    442 	before building libc.
    443 
    444 20011029:
    445 	The new document BUILDING.mdoc (view with nroff | more, or
    446 	see pre-generated .txt and .html versions) describes the build
    447 	procedure in great detail.  BUILDING, and the USE_NEW_TOOLCHAIN
    448 	build process, are intended in the long run to replace this
    449 	manual update log.
    450 
    451 	Users building a USE_NEW_TOOLCHAIN system should read the
    452 	BUILDING document for caveats.  Generally, BUILDING supersedes
    453 	UPDATING for these systems, as tool updating is taken care of
    454 	by the new build system.
    455 
    456 20011028:
    457 	src/etc/Makefile now needs install to be able to handle
    458 	symlinks that point to nowhere. A bug in install that
    459 	prevented this was corrected.
    460 
    461 	Solution: update and reinstall usr.bin/xinstall
    462 	Better Solution: Use the new toolchain and it will just work
    463 	for you.
    464 
    465 20011006:
    466 	/etc/mtree/NetBSD.dist has been updated to take advantage of
    467 	absolute path support added to mtree(8). Older mtree(8)s don't
    468 	understand the format.
    469 
    470 	Solution: update and reinstall usr.sbin/mtree
    471 
    472 20011004:
    473 	Crunchgen has been updated to work via reach-over makefiles. Updating
    474 	is suggested before running a snapshot build
    475 
    476 20010915:
    477 	The new "ubcperf" code committed by Chuck Silvers removed
    478 	a header file, uvm/uvm_vnode.h.  There may be stale .depend
    479 	files that still reference this file.
    480 
    481 	Solution: "make cleandir && make dependall" in affected
    482 	directories.
    483 
    484 20010803:
    485 	grep.info is now built from grep.texi using makeinfo.  Since it
    486 	requires makeinfo v4.0, you need to install new texinfo before
    487 	building gnu/usr.bin/grep.  To install new texinfo, please follow
    488 	the instruction described in 20010726 entry.
    489 
    490 20010803: 
    491 	(i386 only): i386 kernel now uses new instructions like
    492 	`fxsave' which old gas doesn't understand.  To build the
    493 	kernel successfully, you need to build and install a new toolchain, 
    494 	(i.e., build.sh -t) or 	(temporarily) comment out "options I686_CPU" 
    495 	from your kernel configuration until you rebuild your userland.
    496 	See 20011029 above and BUILDING file in this directory for more information.
    497 	[updated 20020630 since i386 gas moved when USE_NEW_TOOLCHAIN enabled]
    498 
    499 20010731:
    500 	Bootloader update on ELF platforms.  DDB in kernels from before
    501 	this will be unable to read symbol tables provided by newer
    502 	bootloaders.
    503 
    504 20010726:
    505 	Texinfo was updated to 4.0.  To avoid failures when trying to
    506 	build the included texinfo files, do:
    507 
    508 	cd src/gnu/usr.bin/texinfo
    509 	make MKINFO=no dependall install
    510 
    511 20010718:
    512 	Enabled correct .init/.fini processing in crt0.  The way this
    513 	was done was to change a -I directive to cc(1), which means
    514 	make(1) will have a stale dependency (it will be checking the
    515 	timestamp on the wrong "dot_init.h").
    516 
    517 	The symptom you will see is that new programs die with SIGSEGV
    518 	if you have a stale dependency.
    519 
    520 	Solution: "make cleandir" in both lib/csu and libexec/ld.elf_so
    521 	before starting your build.
    522 
    523 20010628:
    524 	A construct was added to uvm_page.h that uncovered a bug
    525 	in lint(1).  If you get a warning/error about a non-portable
    526 	bitfield, update your lint(1) before proceeding.
    527 
    528 20010226:
    529 	Added named user/group to system. Need to hand add this in or builds
    530 	will break as mtree aborts early.
    531 
    532 	To work around add by hand:
    533 
    534 	named:*:14:
    535 
    536 	to /etc/group and add:
    537 
    538 	named:*:14:14::0:0:Named pseudo-user:/var/named:/sbin/nologin
    539 
    540 	to master.passwd (use vipw for instance if doing by hand).
    541 
    542 	Now a make build should progress.
    543 
    544 20010219:
    545 	get/setprogname() added. Any hostprogs that may use this will need
    546 	to be bootstrapped manually until the host system is current.
    547 
    548 	Known problems: sys/arch/macppc/stand/fixcoff
    549 			usr.sbin/config (adding -DMAKE_BOOTSTRAP to
    550 			  CFLAGS and rebuilding should work)
    551 			usr.sbin/mdsetimage - Build a static copy if
    552 			  building a snapshot before fully bootstrapped.
    553 
    554 20010204:
    555 	prepare the code to compile with stricter gcc flags. in
    556 	particular start eliminating redundant declarations. Yacc
    557 	needs to be installed before make build.
    558 
    559 20010114:
    560 	introduce .if commands(target) in make(1). You need to
    561 	bring everything up-to-date first, then without installing
    562 	anything make and install in usr.bin/make, then proceed
    563 	with make build.
    564 
    565 20010101:
    566 	bsd.subdir.mk committed 20001230 had a bug which caused
    567 	afterinstall targets to run too soon; update again.
    568 
    569 20001230:
    570 	New share/mk files needed to support .WAIT in SUBDIR variables.
    571 	If you get make errors, 
    572 		(cd share/mk; make install)
    573 	Also, PRINTOBJDIR has changed and is now used more heavily.
    574 
    575 20001019:
    576 	The `ca' device driver has been replaced by `ld'; although the
    577 	major and minor numbers haven't changed, you should update your /dev
    578 	directory.
    579 
    580 20000929:
    581 	The following make directives are obsoleted.
    582 	MKCRYPTO_RSA NOCRYPTO_RSA NOCRYPTO_RC5 NOCRYPTO_IDEA 
    583 	By default, RSA is built into libcrypto.  IDEA and RC5 will not be
    584 	built into libcrypto.  By using MKCRYPTO_{RC5,IDEA}, you can build
    585 	additional library libcrypto_{idea,rc5}.
    586 
    587 
    588 Hints for a more successful build:
    589 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    590     Build a new kernel first:
    591 	This makes sure that any new system calls or features
    592 	   expected by the new userland will be present.  This
    593 	   helps to avoid critical errors when upgrading.
    594     Use object directories:
    595 	This helps to keep stale object
    596 	   files from polluting the build if a Makefile "forgets"
    597 	   about one.  It also makes it easier to clean up after
    598 	   a build.  It's also necessary if you want to use the
    599 	   same source tree for multiple machines.
    600 	   To use object directories:
    601 	    a) cd /usr/src ; make cleandir
    602 	    b) Add "OBJMACHINE=yes" to /etc/mk.conf
    603 	    c) Add "MKOBJDIRS=yes" to /etc/mk.conf
    604 	    d) cd /usr/src ; make build
    605 	   Note that running "make obj" in a directory will create
    606 	   in obj.$MACHINE directory.
    607     Build to a DESTDIR:
    608 	This helps to keep old
    609 	   installed files (especially libraries) from interfering
    610 	   with the new build.
    611 	   To build to a DESTDIR, set the DESTDIR environment
    612 	   variable before running make build.  It should be set to
    613 	   the pathname of an initially empty directory.
    614 	   Problems: you might need to update critical utilities
    615 		without using DESTDIR since nothing is executed
    616 		from what is installed in DESTDIR.
    617 		(See critical utils, below)
    618     Build often:
    619 	This keeps critical utilities current enough to not choke
    620 	on any other part of the source tree that depends on up to
    621 	date functionality.
    622  
    623 What to do if things don't work:
    624 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    625 When things don't work there is usually a few things that commonly
    626 should be done.
    627     1)	make includes
    628 	This should be done automatically by make build.
    629     2)  cd share/mk && make install
    630 	Again, automatically done by make build.
    631 
    632 Failsafe rebuild of a small part of the tree:
    633 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    634 To make sure you rebuild something correctly you want to do
    635 something like the following:
    636     1)  Make sure the includes and .mk files are up to date.
    637     2)  Make sure any program used to build the particular
    638 	utility is up to date.  (yacc, lex, etc...)
    639     3)  cd ...path/to/util...
    640 	make cleandir
    641 	rm ...all obj directories...
    642 	make cleandir			# yes, again
    643 	make obj
    644 	make depend && make
    645 
    646 Failsafe rebuild of the entire tree:
    647 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    648 If you really want to make sure the source tree is clean and
    649 ready for a build try the following.  Note that sourcing /etc/mk.conf
    650 (a make(1) Makefile) in this manner is not right, and will not work
    651 for anyone who uses any make(1) features in /etc/mk.conf.
    652 
    653 ---cut here---
    654 #!/bin/sh
    655 . /etc/mk.conf
    656 
    657 if [ -z $NETBSDSRCDIR ] ; then
    658     NETBSDSRCDIR=/usr/src
    659 fi
    660 if [ \! -d $NETBSDSRCDIR ] ; then
    661     echo Unable to find sources
    662     exit 1
    663 fi
    664 find $NETBSDSRCDIR -name \*.o -o -name obj.\* -o -name obj -exec rm \{\} \;
    665 
    666 if [ -z $BSDOBJDIR ] ; then
    667     BSDOBJDIR=/usr/obj
    668 fi
    669 if [ -d $BSDOBJDIR ] ; then
    670     rm -rf $BSDOBJDIR
    671 fi
    672 
    673 cd $NETBSDSRCDIR && make cleandir
    674 
    675 ---cut here---
    676 
    677 Critical utilities:
    678 ^^^^^^^^^^^^^^^^^^^
    679 	gnu/usr.bin/egcs
    680 	usr.bin/compile_et
    681 	usr.bin/make
    682 	usr.bin/yacc
    683 	usr.bin/lex
    684 	usr.bin/xlint
    685 	usr.sbin/config
    686 
    687 Other problems and possible solutions:
    688 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    689 Symptom:Unreasonable compiler errors.
    690 Fix:	Rebuild gnu/usr.bin/egcs
    691 
    692 Symptom:Complaints involving a Makefile.
    693 Fix:	Rebuild usr.bin/make:
    694 	cd usr.bin/make && make && make install
    695 	Or, a failsafe method if that doesn't work:
    696 	cd usr.bin/make && cc *.c */*.c -I . -o make && mv make /usr/bin
    697 
    698 Fix:	Make sure .mk files are up to date.
    699 	cd share/mk && make install
    700 
    701 Symptom:Kernel `config' fails to configure any kernel, including GENERIC.
    702 Fix:	Rebuild usr.sbin/config
    703 
    704 Symptom:
    705 Fix:	Rebuild usr.bin/yacc
    706 
    707 Symptom:
    708 Fix:	Rebuild usr.bin/lex
    709 
    710 Symptom:
    711 Fix:	rm /usr/lib/libbfd.a
    712 
    713 Symptom:Obsolete intermediate files are used during compilation
    714 Fix:	Try the following sequence of commands in the directory in question.
    715 	make cleandir; rm `make print-objdir`; make cleandir; make obj
    716 	(If you built the tree without "make obj" in the past, obsolete files
    717 	may remain.  The command tries to clean everything up)
    718 
    719 Symptom:.../sysinst/run.c:xx: warning: initialization from incompatible pointer type
    720 Fix:	Rebuild and install usr.bin/menuc
    721 
    722 Symptom:mklocale not found during build in share/locale/ctype
    723 Fix:	Build and install usr.bin/mklocale
    724 
    725 Symptom:undefined reference to `__assert13' or `__unsetenv13'
    726 Fix:    Rebuild and install lib/libc
    727 
    728 Symptom:usr.sbin/config fails to build.
    729 Fix:	Try building with -DMAKE_BOOTSTRAP added to CFLAGS in Makefile.
    730 
    731 Symptom:undefined reference to `getprogname' or `setprogname'
    732 Fix:    Rebuild and install lib/libc
    733 
    734 Symptom:lint does not understand the '-X' option
    735 Fix:    May need to build & install libs with NOLINT=1 before rebuilding lint
    736