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