UPDATING revision 1.2 
1$NetBSD: UPDATING,v 1.2 2000/08/20 15:43:43 mrg 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
1120000623:
12	MKCRYPTO and friends added to share/mk/bsd.own.mk.
13	'cd share/mk ; make install' needed before make build.
14
15
16Hints for a more successful build:
17^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
18    Build a new kernel first:
19	This makes sure that any new system calls or features
20	   expected by the new userland will be present.  This
21	   helps to avoid critical errors when upgrading.
22    Use object directories:
23	This helps to keep stale object
24	   files from polluting the build if a Makefile "forgets"
25	   about one.  It also makes it easier to clean up after
26	   a build.  It's also necessary if you want to use the
27	   same source tree for multiple machines.
28	   To use object directories:
29	    a) cd /usr/src ; make cleandir
30	    b) Add "OBJMACHINE=yes" to /etc/mk.conf
31	    c) Add "MKOBJDIRS=yes" to /etc/mk.conf
32	    d) cd /usr/src ; make build
33	   Note that running "make obj" in a directory will create
34	   in obj.$MACHINE directory.
35    Build to a DESTDIR:
36	This helps to keep old
37	   installed files (especially libraries) from interfering
38	   with the new build.
39	   To build to a DESTDIR, set the DESTDIR environment
40	   variable before running make build.  It should be set to
41	   the pathname of an initially empty directory.
42	   Problems: you might need to update critical utilities
43		without using DESTDIR since nothing is executed
44		from what is installed in DESTDIR.
45		(See critical utils, below)
46    Build often:
47	This keeps critical utilities current enough to not choke
48	on any other part of the source tree that depends on up to
49	date functionality.
50 
51What to do if things don't work:
52^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
53When things don't work there is usually a few things that commonly
54should be done.
55    1)	make includes
56	This should be done automatically by make build.
57    2)  cd share/mk && make install
58	Again, automatically done by make build.
59
60Failsafe rebuild of a small part of the tree:
61^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
62To make sure you rebuild something correctly you want to do
63something like the following:
64    1)  Make sure the includes and .mk files are up to date.
65    2)  Make sure any program used to build the particular
66	utility is up to date.  (yacc, lex, etc...)
67    3)  cd ...path/to/util...
68	make cleandir
69	rm ...all obj directories...
70	make cleandir			# yes, again
71	make obj
72	make depend && make
73
74Failsafe rebuild of the entire tree:
75^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
76If you really want to make sure the source tree is clean and
77ready for a build try the following.  Note that sourcing /etc/mk.conf
78(a make(1) Makefile) in this manner is not right, and will not work
79for anyone who uses any make(1) features in /etc/mk.conf.
80
81---cut here---
82#!/bin/sh
83. /etc/mk.conf
84
85if [ -z $BSDSRCDIR ] ; then
86    BSDSRCDIR=/usr/src
87fi
88if [ \! -d $BSDSRCDIR ] ; then
89    echo Unable to find sources
90    exit 1
91fi
92find $BSDSRCDIR -name \*.o -o -name obj.\* -o -name obj -exec rm \{\} \;
93
94if [ -z $BSDOBJDIR ] ; then
95    BSDOBJDIR=/usr/obj
96fi
97if [ -d $BSDOBJDIR ] ; then
98    rm -rf $BSDOBJDIR
99fi
100
101cd $BSDSRCDIR && make cleandir
102
103---cut here---
104
105Critical utilities:
106^^^^^^^^^^^^^^^^^^^
107	gnu/usr.bin/egcs
108	usr.bin/make
109	usr.bin/yacc
110	usr.bin/lex
111	usr.sbin/config
112	crypto-*/usr.bin/compile_et
113	crypto-*/usr.bin/make_cmds
114
115Other problems and possibly solutions:
116^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
117Symptom:Unreasonable compiler errors.
118Fix:	Rebuild gnu/usr.bin/egcs
119
120Symptom:Complaints involving a Makefile.
121Fix:	Make sure .mk files are up to date.
122	cd share/mk && make install
123Fix:	Rebuild usr.bin/make
124
125Symptom:Kernel `config' fails to configure any kernel, including GENERIC.
126Fix:	Rebuild usr.sbin/config
127
128Symptom:
129Fix:	Rebuild usr.bin/yacc
130
131Symptom:
132Fix:	Rebuild usr.bin/lex
133
134Symptom:
135Fix:	rm /usr/lib/libbfd.a
136