UPDATING revision 1.77
1$NetBSD: UPDATING,v 1.77 2002/11/26 23:35:42 lukem Exp $ 2 3This file is intended to be a brief introduction to the build 4process and a reference on what to do if something doesn't work. 5 6For a more detailed description see Makefile. 7 8Recent changes: 9^^^^^^^^^^^^^^^ 10 1120021126: 12 The mk.conf(5) variable SYS_INCLUDE has been deprecated, 13 including the optional "SYS_INCLUDE=symlinks" support. 14 All header files, including <sys/*.h> are copied into 15 /usr/include. 16 1720021121: 18 The C run-time support files crtbegin.o and crtend.o 19 (and their companions crtbeginS.o and crtendS.o) were 20 split up, with new crti.o and crtn.o files resulting. 21 This means that libtool needs to be rebuilt once the 22 new libraries are installed. The process of rebuilding 23 libtool will cause it to automatically notice the new 24 required files, but it *must* be rebuilt in order to 25 do this. 26 27 An out-of-date libtool will result in shared libraries 28 which lack _init() and _fini() routines, which means that 29 their global contructors/destructors will not be invoked. 30 3120021121: 32 A bug related to how ARM ELF objects were tagged has been 33 corrected. 34 35 NetBSD ARM ELF uses the soft-VFP floating point model by 36 default. However, the assembler lacked support for marking 37 objects as using the VFP floating point format, and the 38 compiler was no properly passing the flag indicating "soft-VFP" 39 to the assembler. 40 41 Unfortunately, this means that the linker will now consider 42 old (i.e. not marked "softvfp") NetBSD ARM ELF objects to be 43 incompatible with new (properly marked) objects. 44 45 The problem will only manifest itself if you attempt to compile 46 a new program using the fixed toolchain, and link that program 47 against old libraries which do not have the proper "softvfp" 48 markings. ALL OF YOUR EXISTING BINARIES AND SHARED LIBRARIES 49 WILL CONTINUE TO WORK PROPERLY. 50 51 The only work-around for the problem is to recompile all of 52 the libraries on the system. The easiest way to do this for 53 system libraries is to install a binary snapshot; there are 54 generally available on releng.netbsd.org. Any packages you 55 have installed which supply libraries will have to be recompiled 56 if you wish to link new programs against those libraries. 57 58 If you have questions about this matter, please contact 59 port-arm@netbsd.org. 60 6120021011: 62 Systrace has been improved to support privilege elevation. 63 Updating the kernel requires the userland part of systrace 64 to be rebuild. 65 6620021010: 67 The config(8) grammar was changed to allow options to register 68 dependencies on attributes, as well as other options. Users 69 must update and reinstall usr.sbin/config before building a new 70 kernel. 71 7220021009: 73 A new attribute dependency syntax was introduced to config(8), 74 which is now used by the SCSI configuration description. Users 75 must update and reinstall usr.sbin/config before building a new 76 kernel. 77 7820021003: 79 Several changes have been made to the autoconfiguration 80 framework. Users must update and reinstall usr.sbin/config 81 before building a new kernel. 82 8320021001: 84 The i386mp branch has been merged. To compile a kernel, users 85 will need to add the option 'cpu* at mainbus?' to their configuration 86 file. Multiprocessor kernels will need 87 ioapic* at mainbus? apid ? 88 options MULTIPROCESSOR 89 options COM_MPLOCK 90 9120020922: 92 MKDYNAMICROOT=yes enabled by default, which means that 93 certain shared libraries are installed into /lib, the shared 94 linker is installed into /libexec, and all programs in /bin 95 and /sbin are dynamically linked. 96 If you do not use "make build", you should ensure that 97 you have the libraries and shared linker in the new locations, 98 with: 99 make do-lib-csu do-lib-libc do-lib do-gnu-lib do-ld.elf_so 100 10120020917: 102 USE_NEW_TOOLCHAIN has been replaced with: 103 - TOOLCHAIN_MISSING -- set to "yes" on platforms for which 104 there is no working in-tree toolchain (hppa, ns32k, sh5, 105 x86_64). 106 - EXTERNAL_TOOLCHAIN -- if defined by the user, points to the 107 root ofan external toolchain (e.g. /usr/local/gnu). This 108 enables the cross-build framework even for TOOLCHAIN_MISSING 109 platforms. 110 11120020906: 112 gehenna-devsw has been merged into the trunk. Need to update and 113 reinstall usr.sbin/config before build the kernel. 114 11520020822: 116 Crunched rescue tools (contents of /bin and /sbin, plus others) 117 are now provided in /rescue. 118 119 To ensure that these are built statically linked (no matter 120 what the setting of LDSTATIC is), use a crunchgen(1) built 121 from sources newer than 20020820 (see the next entry). 122 12320020820: 124 crunchgen(1) changed to ensure that the generated program 125 is statically linked. 126 127 Solution: update and reinstall usr.bin/crunch 128 12920020515: 130 sshd user/group has been added. Need to hand add this in, or sshd 131 will not let you log in (with default, or UsePrivlegeSeparation=yes) 132 133 Add the following into /etc/group: 134 135 sshd:*:16: 136 137 and the following to /etc/master.passwd (via vipw): 138 139 sshd:*:16:16::0:0:& pseudo-user:/var/chroot/sshd:/sbin/nologin 140 141 also /var/chroot/sshd directory needs to be present (digged as a part of 142 build process). 143 14420020426: 145 NBUILDJOBS obsoleted in favor of just using -j. 146 14720020426: 148 etc/postinstall added, which performs various checks for 149 configuration file updates and changes, and can fix most of 150 the problems identified. 151 This should make it much easier to upgrade a system's 152 configuration from earlier systems (as far back as NetBSD 1.5). 153 15420020320: 155 <bsd.lib.mk> needs a new install(1) for it's "-a cmd" support. 156 build and install at usr.bin/xinstall before the build. 157 15820020319: 159 raw IPv6 socket now makes strict checking for sa_family and sa_len 160 on send(2) operation. be sure to have sbin/rtsol and usr.sbin/rtsold 161 newer than November 2001 when you upgrade the kernel. 162 16320020311: 164 ssh configuration files were moved from /etc to /etc/ssh. Beware 165 if you restart your machine from remote. Note that sshd.conf needs 166 to be changed (due to the use of "/etc" inside). 167 16820020223: 169 Users of the VAX port will need to rebuild and install gas 170 so it deal with the now present register prefix used in all 171 the VAX assembly files. 172 17320020118: 174 175 ntpd user/group has been added. Need to hand add this in or builds 176 will break as mtree aborts early. 177 178 Add the following into /etc/group: 179 180 ntpd:*:15: 181 182 and the following to /etc/master.passwd (via vipw): 183 184 ntpd:*:15:15::0:0:Ntpd pseudo-user:/var/chroot/ntpd:/sbin/nologin 185 18620011207: 187 188 If you're attempting to build a snapshot on sparc64 and are getting 189 reloc errors from the toolchain groff binary this means your native 190 toolchain has some broken C++ bits. 191 192 To fix: 193 194 Build a new toolchain (i.e. build.sh -t) 195 Use the new toolchain to build and install natively (i.e. /usr/lib) 196 197 gnu/lib/libgcc 198 gnu/lib/libstdc++ 199 200 After this a snapshot will be able to be built. 201 20220011201: 203 In order for a sparc64 build to work you must have a working awk. If 204 you've built and installed a system with the new toolchain up to this 205 point you do not have a working awk as its ability to do floating 206 point is broken. 207 208 To build: 209 210 remake and install gnu/lib/libgcc 211 remake and install gnu/usr.bin/gawk into /usr/bin (make sure it links 212 against the new libgcc.a) 213 21420011128: 215 Kernel config information was changed to use defflag in 216 the various "files" files. Bug fixes to config(8) are 217 required in order for this to work properly. Make sure 218 to build and install in usr.sbin/config before attempting 219 to build a new kernel. 220 22120011030: 222 libc/locale/wcstod.c now needs new lint(1). Update lint(1) 223 before building libc. 224 22520011029: 226 The new document BUILDING.mdoc (view with nroff | more, or 227 see pre-generated .txt and .html versions) describes the build 228 procedure in great detail. BUILDING, and the USE_NEW_TOOLCHAIN 229 build process, are intended in the long run to replace this 230 manual update log. 231 232 Users building a USE_NEW_TOOLCHAIN system should read the 233 BUILDING document for caveats. Generally, BUILDING supersedes 234 UPDATING for these systems, as tool updating is taken care of 235 by the new build system. 236 23720011028: 238 src/etc/Makefile now needs install to be able to handle 239 symlinks that point to nowhere. A bug in install that 240 prevented this was corrected. 241 242 Solution: update and reinstall usr.bin/xinstall 243 Better Solution: Use the new toolchain and it will just work 244 for you. 245 24620011006: 247 /etc/mtree/NetBSD.dist has been updated to take advantage of 248 absolute path support added to mtree(8). Older mtree(8)s don't 249 understand the format. 250 251 Solution: update and reinstall usr.sbin/mtree 252 25320011004: 254 Crunchgen has been updated to work via reach-over makefiles. Updating 255 is suggested before running a snapshot build 256 25720010915: 258 The new "ubcperf" code committed by Chuck Silvers removed 259 a header file, uvm/uvm_vnode.h. There may be stale .depend 260 files that still reference this file. 261 262 Solution: "make cleandir && make dependall" in affected 263 directories. 264 26520010803: 266 grep.info is now built from grep.texi using makeinfo. Since it 267 requires makeinfo v4.0, you need to install new texinfo before 268 building gnu/usr.bin/grep. To install new texinfo, please follow 269 the instruction described in 20010726 entry. 270 27120010803: 272 (i386 only): i386 kernel now uses new instructions like 273 `fxsave' which old gas doesn't understand. To build the 274 kernel successfully, you need to build and install a new toolchain, 275 (i.e., build.sh -t) or (temporarily) comment out "options I686_CPU" 276 from your kernel configuration until you rebuild your userland. 277 See 20011029 above and BUILDING file in this directory for more information. 278 [updated 20020630 since i386 gas moved when USE_NEW_TOOLCHAIN enabled] 279 28020010731: 281 Bootloader update on ELF platforms. DDB in kernels from before 282 this will be unable to read symbol tables provided by newer 283 bootloaders. 284 28520010726: 286 Texinfo was updated to 4.0. To avoid failures when trying to 287 build the included texinfo files, do: 288 289 cd src/gnu/usr.bin/texinfo 290 make MKINFO=no dependall install 291 29220010718: 293 Enabled correct .init/.fini processing in crt0. The way this 294 was done was to change a -I directive to cc(1), which means 295 make(1) will have a stale dependency (it will be checking the 296 timestamp on the wrong "dot_init.h"). 297 298 The symptom you will see is that new programs die with SIGSEGV 299 if you have a stale dependency. 300 301 Solution: "make cleandir" in both lib/csu and libexec/ld.elf_so 302 before starting your build. 303 30420010628: 305 A construct was added to uvm_page.h that uncovered a bug 306 in lint(1). If you get a warning/error about a non-portable 307 bitfield, update your lint(1) before proceeding. 308 30920010226: 310 Added named user/group to system. Need to hand add this in or builds 311 will break as mtree aborts early. 312 313 To work around add by hand: 314 315 named:*:14: 316 317 to /etc/group and add: 318 319 named:*:14:14::0:0:Named pseudo-user:/var/named:/sbin/nologin 320 321 to master.passwd (use vipw for instance if doing by hand). 322 323 Now a make build should progress. 324 32520010219: 326 get/setprogname() added. Any hostprogs that may use this will need 327 to be bootstrapped manually until the host system is current. 328 329 Known problems: sys/arch/macppc/stand/fixcoff 330 usr.sbin/config (adding -DMAKE_BOOTSTRAP to 331 CFLAGS and rebuilding should work) 332 usr.sbin/mdsetimage - Build a static copy if 333 building a snapshot before fully bootstrapped. 334 33520010204: 336 prepare the code to compile with stricter gcc flags. in 337 particular start eliminating redundant declarations. Yacc 338 needs to be installed before make build. 339 34020010114: 341 introduce .if commands(target) in make(1). You need to 342 bring everything up-to-date first, then without installing 343 anything make and install in usr.bin/make, then proceed 344 with make build. 345 34620010101: 347 bsd.subdir.mk committed 20001230 had a bug which caused 348 afterinstall targets to run too soon; update again. 349 35020001230: 351 New share/mk files needed to support .WAIT in SUBDIR variables. 352 If you get make errors, 353 (cd share/mk; make install) 354 Also, PRINTOBJDIR has changed and is now used more heavily. 355 35620001019: 357 The `ca' device driver has been replaced by `ld'; although the 358 major and minor numbers haven't changed, you should update your /dev 359 directory. 360 36120000929: 362 The following make directives are obsoleted. 363 MKCRYPTO_RSA NOCRYPTO_RSA NOCRYPTO_RC5 NOCRYPTO_IDEA 364 By default, RSA is built into libcrypto. IDEA and RC5 will not be 365 built into libcrypto. By using MKCRYPTO_{RC5,IDEA}, you can build 366 additional library libcrypto_{idea,rc5}. 367 368 369Hints for a more successful build: 370^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 371 Build a new kernel first: 372 This makes sure that any new system calls or features 373 expected by the new userland will be present. This 374 helps to avoid critical errors when upgrading. 375 Use object directories: 376 This helps to keep stale object 377 files from polluting the build if a Makefile "forgets" 378 about one. It also makes it easier to clean up after 379 a build. It's also necessary if you want to use the 380 same source tree for multiple machines. 381 To use object directories: 382 a) cd /usr/src ; make cleandir 383 b) Add "OBJMACHINE=yes" to /etc/mk.conf 384 c) Add "MKOBJDIRS=yes" to /etc/mk.conf 385 d) cd /usr/src ; make build 386 Note that running "make obj" in a directory will create 387 in obj.$MACHINE directory. 388 Build to a DESTDIR: 389 This helps to keep old 390 installed files (especially libraries) from interfering 391 with the new build. 392 To build to a DESTDIR, set the DESTDIR environment 393 variable before running make build. It should be set to 394 the pathname of an initially empty directory. 395 Problems: you might need to update critical utilities 396 without using DESTDIR since nothing is executed 397 from what is installed in DESTDIR. 398 (See critical utils, below) 399 Build often: 400 This keeps critical utilities current enough to not choke 401 on any other part of the source tree that depends on up to 402 date functionality. 403 404What to do if things don't work: 405^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 406When things don't work there is usually a few things that commonly 407should be done. 408 1) make includes 409 This should be done automatically by make build. 410 2) cd share/mk && make install 411 Again, automatically done by make build. 412 413Failsafe rebuild of a small part of the tree: 414^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 415To make sure you rebuild something correctly you want to do 416something like the following: 417 1) Make sure the includes and .mk files are up to date. 418 2) Make sure any program used to build the particular 419 utility is up to date. (yacc, lex, etc...) 420 3) cd ...path/to/util... 421 make cleandir 422 rm ...all obj directories... 423 make cleandir # yes, again 424 make obj 425 make depend && make 426 427Failsafe rebuild of the entire tree: 428^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 429If you really want to make sure the source tree is clean and 430ready for a build try the following. Note that sourcing /etc/mk.conf 431(a make(1) Makefile) in this manner is not right, and will not work 432for anyone who uses any make(1) features in /etc/mk.conf. 433 434---cut here--- 435#!/bin/sh 436. /etc/mk.conf 437 438if [ -z $NETBSDSRCDIR ] ; then 439 NETBSDSRCDIR=/usr/src 440fi 441if [ \! -d $NETBSDSRCDIR ] ; then 442 echo Unable to find sources 443 exit 1 444fi 445find $NETBSDSRCDIR -name \*.o -o -name obj.\* -o -name obj -exec rm \{\} \; 446 447if [ -z $BSDOBJDIR ] ; then 448 BSDOBJDIR=/usr/obj 449fi 450if [ -d $BSDOBJDIR ] ; then 451 rm -rf $BSDOBJDIR 452fi 453 454cd $NETBSDSRCDIR && make cleandir 455 456---cut here--- 457 458Critical utilities: 459^^^^^^^^^^^^^^^^^^^ 460 gnu/usr.bin/egcs 461 usr.bin/compile_et 462 usr.bin/make 463 usr.bin/yacc 464 usr.bin/lex 465 usr.bin/xlint 466 usr.sbin/config 467 468Other problems and possible solutions: 469^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 470Symptom:Unreasonable compiler errors. 471Fix: Rebuild gnu/usr.bin/egcs 472 473Symptom:Complaints involving a Makefile. 474Fix: Rebuild usr.bin/make: 475 cd usr.bin/make && make && make install 476 Or, a failsafe method if that doesn't work: 477 cd usr.bin/make && cc *.c */*.c -I . -o make && mv make /usr/bin 478 479Fix: Make sure .mk files are up to date. 480 cd share/mk && make install 481 482Symptom:Kernel `config' fails to configure any kernel, including GENERIC. 483Fix: Rebuild usr.sbin/config 484 485Symptom: 486Fix: Rebuild usr.bin/yacc 487 488Symptom: 489Fix: Rebuild usr.bin/lex 490 491Symptom: 492Fix: rm /usr/lib/libbfd.a 493 494Symptom:Obsolete intermediate files are used during compilation 495Fix: Try the following sequence of commands in the directory in question. 496 make cleandir; rm `make print-objdir`; make cleandir; make obj 497 (If you built the tree without "make obj" in the past, obsolete files 498 may remain. The command tries to clean everything up) 499 500Symptom:.../sysinst/run.c:xx: warning: initialization from incompatible pointer type 501Fix: Rebuild and install usr.bin/menuc 502 503Symptom:mklocale not found during build in share/locale/ctype 504Fix: Build and install usr.bin/mklocale 505 506Symptom:undefined reference to `__assert13' 507Fix: Rebuild and install lib/libc 508 509Symptom:usr.sbin/config fails to build. 510Fix: Try building with -DMAKE_BOOTSTRAP added to CFLAGS in Makefile. 511 512Symptom:undefined reference to `getprogname' or `setprogname' 513Fix: Rebuild and install lib/libc 514 515Symptom:lint does not understand the '-X' option 516Fix: May need to build & install libs with NOLINT=1 before rebuilding lint 517