NetBSD-Docs archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
...and now UPDATING
Through the wonders of random PRs, I ran across install/14078, which
notes that (as of 2003) the hints section of UPDATING was out of date.
I think some bits have been updated since, but some things are still
not so great. So, how about the following patch?
(This was extracted with diff -uw to avoid reporting a bunch of
formatting adjustments, or at least, avoid reporting them any more
than necessary.)
Another reasonable alternative is just to nuke the entire section, on
the grounds that doing full builds without build.sh is no longer
something that needs to be in front-line documentation.
Index: UPDATING
===================================================================
RCS file: /cvsroot/src/UPDATING,v
retrieving revision 1.170
diff -u -w -r1.170 UPDATING
--- UPDATING 28 Jan 2008 03:30:26 -0000 1.170
+++ UPDATING 29 Mar 2008 05:00:41 -0000
@@ -145,36 +145,60 @@
new build products from interfering with the running
system. This will allow you to ignore most of the
other advice in this file.
- Build a new kernel first:
+ If you don't use build.sh, do use tools:
+ This will, as one of the first steps in the build,
+ compile all the tools used in the rest of the build.
+ This will avoid most bootstrapping problems and
+ prevent having to recompile assorted programs by
+ hand. Add USETOOLS=yes to /etc/mk.conf if it isn't
+ already the default, which it will be in most cases.
+ If you don't use tools:
+ You may have to recompile and install various critical
+ utilities by hand before you can build the system.
+ Figuring out/knowing which things you need to rebuild
+ is sometimes not entirely trivial. See below, but
+ this is not recommended. Really, just use build.sh.
+
+ Build and boot a new kernel first before building userland:
This makes sure that any new system calls or features
expected by the new userland will be present. This
- helps to avoid critical errors when upgrading.
- Use object directories:
- This helps to keep stale object
- files from polluting the build if a Makefile "forgets"
- about one. It also makes it easier to clean up after
- a build. It's also necessary if you want to use the
- same source tree for multiple machines.
- To use object directories with build.sh:
- a) invoke build.sh with the "-M" or "-O" options.
- To use object directories without using build.sh:
- a) cd /usr/src ; make cleandir
- b) Add "OBJMACHINE=yes" to /etc/mk.conf
- c) Add "MKOBJDIRS=yes" to /etc/mk.conf
- d) cd /usr/src ; make build
- Note that running "make obj" in a directory will create
- in obj.$MACHINE directory.
+ helps to avoid critical errors when upgrading. Also,
+ if the new kernel does not survive the userland build
+ it's a good sign you may want to go back to the old
+ kernel and hold off on the update.
+
+ Always use object directories.
+ This keeps generated files from interfering with CVS,
+ helps to prevent build problems caused by stale
+ objects, and makes cleaning builds easier. It also
+ can allow using the same source tree to build for
+ multiple machine types. When using build.sh, object
+ directories are made by default. If not using
+ build.sh, do "make obj" before building or add
+ "MKOBJDIRS=yes" to /etc/mk.conf. To make per-machine
+ object directories, add "OBJMACHINE=yes" to
+ /etc/mk.conf. For greater control, you can use the
+ "-M" or "-O" options of build.sh or the make
+ variables they set. See BUILDING for further
+ information.
+ Note that running "make obj" in a directory will
+ create its corresponding object directory.
+
Build to a DESTDIR:
- This helps to keep old installed files (especially libraries)
- from interfering with the new build.
- To build to a DESTDIR with build.sh, use the "-D" option.
- To build to a DESTDIR without using build.sh, set the DESTDIR
- environment variable before running make build. It should be
- set to the pathname of an initially empty directory.
- Problems: if you do not use build.sh, you might need to
- update critical utilities without using DESTDIR since
- nothing is executed from what is installed in DESTDIR.
- (See critical utils, below.)
+ This helps to keep old installed files (especially
+ libraries) from interfering with the new build.
+ This is the default when using build.sh; the location
+ can be changed using the "-D" option.
+ To build to a DESTDIR without using build.sh, set the
+ DESTDIR environment variable before running make
+ build. It should be set to the pathname of an
+ initially empty directory.
+ Note that if you don't use either build.sh or tools,
+ you may need to recompile more critical utilities
+ more often, because nothing is executed from what is
+ installed in DESTDIR. See below. But again, really,
+ just use build.sh.
+
Build often:
This keeps critical utilities current enough to not choke
on any other part of the source tree that depends on up to
@@ -183,60 +207,115 @@
What to do if things don't work:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-When things don't work there is usually a few things that commonly
-should be done.
- 1) make includes
- This should be done automatically by make build.
- 2) cd share/mk && make install
- Again, automatically done by make build.
+When things don't work there are two basic steps to take first:
+ 1) cd share/mk && make install
+ You can copy share/mk/*.mk into /usr/share/mk by hand if
+ necessary.
+ 2) make includes
+
+These actions should both be done automatically by "make build",
+but sometimes (particularly with changes to bsd.*.mk) the build
+doesn't get that far on its own.
Failsafe rebuild of a small part of the tree:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-To make sure you rebuild something correctly you want to do
-something like the following:
- 1) Make sure the includes and .mk files are up to date.
- 2) Make sure any program used to build the particular
- utility is up to date. (yacc, lex, etc...)
+To rebuild and install one program (or library) safely from
+scratch, do the following:
+ 1) Make sure the includes and .mk files are up to date, as
+ above.
+ 2) Make sure any other program that will be used in the
+ build is up to date. (yacc, lex, etc...)
3) cd ...path/to/util...
make cleandir
rm ...all obj directories...
make cleandir # yes, again
make obj
- make depend && make
+ make dependall install
+
+If this fails because make is trying to run tools from your
+TOOLDIR and they aren't there, try again adding USETOOLS=never
+to the command line for each make invocation.
+
+If the man page won't build, lint starts complaining, or other
+problems arise that are secondary to just getting a current copy
+of the program compiled so you can do a proper build, you can
+set MKMAN=no, MKLINT=no, or other similar control variables on
+the make command line to disable these steps.
+
+You can use this method to rebuild larger subtrees than a single
+program, but in some cases, particularly with lib/, it will fail
+because of magic ordering requirements. (These are known to
+"make build" and handled explicitly there.)
+
+If you go to rebuild something and it won't link, you may need
+to rebuild and reinstall libc (and possibly then other libs,
+too) and then clean and recompile the program again as above.
+Remember to do "make includes" first for any library you
+recompile, which includes doing "make includes" in src/sys and
+src/include before rebuilding libc.
+
+If make becomes completely inoperable, a super-failsafe way to
+rebuild it is like this:
+
+ cd usr.bin/make
+ cc *.c */*.c -I. -o make
+ mv make /usr/bin/make
Failsafe rebuild of the entire tree:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-If you really want to make sure the source tree is clean and
-ready for a build try the following. Note that sourcing /etc/mk.conf
-(a make(1) Makefile) in this manner is not right, and will not work
-for anyone who uses any make(1) features in /etc/mk.conf.
-
----cut here---
-#!/bin/sh
-. /etc/mk.conf
-
-if [ -z $NETBSDSRCDIR ] ; then
- NETBSDSRCDIR=/usr/src
-fi
-if [ \! -d $NETBSDSRCDIR ] ; then
- echo Unable to find sources
- exit 1
-fi
-find $NETBSDSRCDIR -name \*.o -o -name obj.\* -o -name obj -exec rm \{\} \;
-
-if [ -z $BSDOBJDIR ] ; then
- BSDOBJDIR=/usr/obj
-fi
-if [ -d $BSDOBJDIR ] ; then
- rm -rf $BSDOBJDIR
-fi
+To really clean out the tree you can do the following from the
+top of your source tree:
-cd $NETBSDSRCDIR && make cleandir
+ make cleandir
+ find . -type d -name 'obj*' -print0 | xargs -0 rm -rf
+ find . -type l -name 'obj*' -print0 | xargs -0 rm -f
+ make cleandir # yes, again
+ find . -type f -name '*.[do]' -print0 | xargs -0 rm -f
+ find . -type f -name '*.[ps]o' -print0 | xargs -0 rm -f
+ make obj
+ make cleandir # yes, a third time
----cut here---
+This does not by any means necessarily catch every file that
+might have been left behind, but it should catch most of the
+ones likely to cause build problems
+
+Deleting /usr/obj (or whatever other object directory tree you
+may be using) is also helpful.
+
+If your tree still has problems after this it may be necessary
+to use CVS to look for extraneous or unintentionally modified
+files. Do "cvs -n -I! update -dP" and delete or move elsewhere
+any file it complains about being in the way or doesn't think is
+part of the tree (shows up with a '?'). Also examine and perhaps
+revert any files CVS thinks have been modified (that show up
+with a 'M').
+
+Also, however, especially if you're using -current, remember the
+possibility that the build may simply be broken at the moment.
+Despite everyone's efforts to the contrary this still happens
+from time to time. cvs update may help; also check the current-
+users mailing list for other reports of similar problems.
Critical utilities:
^^^^^^^^^^^^^^^^^^^
+If you aren't using build.sh or tools, the best list of programs
+that you might need to rebuild is the list of tools: every
+program that has a directory in src/tools is used in the build
+at some point or for some platform. (That's the whole idea of
+src/tools.) All these utilities are thus critical, but most of
+them won't need to be rebuilt every time.
+
+The short explanation is that you should rebuild whichever tools
+cause problems. (Rebuild them from their primary source
+directories in src/bin or src/usr.bin or wherever, not from
+src/tools.) Unfortunately, sometimes it can be difficult to
+tell exactly what program is at fault. Really, just use
+build.sh.
+
+This is a list of some programs that someone at some unspecified
+prior time thought most prone to causing build breakage if out
+of date:
+
usr.bin/compile_et
usr.bin/make
usr.bin/yacc
@@ -247,24 +326,26 @@
Other problems and possible solutions:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Symptom:Complaints involving a Makefile.
-Fix: Rebuild usr.bin/make:
- cd usr.bin/make && make && make install
- Or, a failsafe method if that doesn't work:
- cd usr.bin/make && cc *.c */*.c -I . -o make && mv make /usr/bin
-
-Fix: Make sure .mk files are up to date.
- cd share/mk && make install
+Fix: Rebuild src/usr.bin/make.
+Fix: Update .mk files from src/share/mk, as above.
Symptom:Kernel `config' fails to configure any kernel, including GENERIC.
-Fix: Rebuild usr.bin/config
-
-Symptom:
-Fix: Rebuild usr.bin/yacc
+ (Note: nowadays config tells you when it needs recompiling.)
+Fix: Rebuild src/usr.bin/config.
-Symptom:
-Fix: Rebuild usr.bin/lex
+Symptom: Compile errors in y.tab.c, y.tab.h, or a .c file
+ matching the name of a .y file.
+Fix: Rebuild src/usr.bin/yacc.
+
+Symptom: Compile errors in lex.yy.c or a .c file matching the
+ name of a .l file.
+Fix: Rebuild src/usr.bin/lex.
+
+Symptom: Compile errors in a .c or .h file matching the
+ name of a .x file.
+Fix: Rebuild src/usr.bin/rpcgen.
-Symptom:
+Symptom: ?
Fix: rm /usr/lib/libbfd.a
Symptom:Obsolete intermediate files are used during compilation
@@ -273,20 +354,21 @@
(If you built the tree without "make obj" in the past, obsolete files
may remain. The command tries to clean everything up)
-Symptom:.../sysinst/run.c:xx: warning: initialization from incompatible
pointer type
-Fix: Rebuild and install usr.bin/menuc
+Symptom: .../sysinst/run.c:xx: warning: initialization from incompatible
+ pointer type
+Fix: Rebuild and install src/usr.bin/menuc.
Symptom:mklocale not found during build in share/locale/ctype
-Fix: Build and install usr.bin/mklocale
+Fix: Build and install src/usr.bin/mklocale.
Symptom:undefined reference to `__assert13' or `__unsetenv13'
-Fix: Rebuild and install lib/libc
+Fix: Rebuild and install src/lib/libc.
Symptom:usr.bin/config fails to build.
Fix: Try building with -DMAKE_BOOTSTRAP added to CFLAGS in Makefile.
Symptom:undefined reference to `getprogname' or `setprogname'
-Fix: Rebuild and install lib/libc
+Fix: Rebuild and install lib/libc.
Symptom:lint does not understand the '-X' option
-Fix: May need to build & install libs with NOLINT=1 before rebuilding lint
+Fix: May need to build & install libs with MKLINT=no before rebuilding lint.
--
David A. Holland
dholland%netbsd.org@localhost
Home |
Main Index |
Thread Index |
Old Index