UPDATING revision 1.7 
1$NetBSD: UPDATING,v 1.7 2000/11/26 17:46:28 ad 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
1120001019:
12	The `ca' device driver has been replaced by `ld'; although the
13	major and minor numbers haven't changed, you should update your /dev
14	directory.
15
1620000929:
17	The following make directives are obsoleted.
18	MKCRYPTO_RSA NOCRYPTO_RSA NOCRYPTO_RC5 NOCRYPTO_IDEA 
19	By default, RSA is built into libcrypto.  IDEA and RC5 will not be
20	bulit into libcrypto.  By using MKCRYPTO_{RC5,IDEA}, you can build
21	additional library libcrypto_{idea,rc5}.
22
2320000623:
24	MKCRYPTO and friends added to share/mk/bsd.own.mk.
25	'cd share/mk ; make install' needed before make build.
26
27
28Hints for a more successful build:
29^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
30    Build a new kernel first:
31	This makes sure that any new system calls or features
32	   expected by the new userland will be present.  This
33	   helps to avoid critical errors when upgrading.
34    Use object directories:
35	This helps to keep stale object
36	   files from polluting the build if a Makefile "forgets"
37	   about one.  It also makes it easier to clean up after
38	   a build.  It's also necessary if you want to use the
39	   same source tree for multiple machines.
40	   To use object directories:
41	    a) cd /usr/src ; make cleandir
42	    b) Add "OBJMACHINE=yes" to /etc/mk.conf
43	    c) Add "MKOBJDIRS=yes" to /etc/mk.conf
44	    d) cd /usr/src ; make build
45	   Note that running "make obj" in a directory will create
46	   in obj.$MACHINE directory.
47    Build to a DESTDIR:
48	This helps to keep old
49	   installed files (especially libraries) from interfering
50	   with the new build.
51	   To build to a DESTDIR, set the DESTDIR environment
52	   variable before running make build.  It should be set to
53	   the pathname of an initially empty directory.
54	   Problems: you might need to update critical utilities
55		without using DESTDIR since nothing is executed
56		from what is installed in DESTDIR.
57		(See critical utils, below)
58    Build often:
59	This keeps critical utilities current enough to not choke
60	on any other part of the source tree that depends on up to
61	date functionality.
62 
63What to do if things don't work:
64^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
65When things don't work there is usually a few things that commonly
66should be done.
67    1)	make includes
68	This should be done automatically by make build.
69    2)  cd share/mk && make install
70	Again, automatically done by make build.
71
72Failsafe rebuild of a small part of the tree:
73^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
74To make sure you rebuild something correctly you want to do
75something like the following:
76    1)  Make sure the includes and .mk files are up to date.
77    2)  Make sure any program used to build the particular
78	utility is up to date.  (yacc, lex, etc...)
79    3)  cd ...path/to/util...
80	make cleandir
81	rm ...all obj directories...
82	make cleandir			# yes, again
83	make obj
84	make depend && make
85
86Failsafe rebuild of the entire tree:
87^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
88If you really want to make sure the source tree is clean and
89ready for a build try the following.  Note that sourcing /etc/mk.conf
90(a make(1) Makefile) in this manner is not right, and will not work
91for anyone who uses any make(1) features in /etc/mk.conf.
92
93---cut here---
94#!/bin/sh
95. /etc/mk.conf
96
97if [ -z $BSDSRCDIR ] ; then
98    BSDSRCDIR=/usr/src
99fi
100if [ \! -d $BSDSRCDIR ] ; then
101    echo Unable to find sources
102    exit 1
103fi
104find $BSDSRCDIR -name \*.o -o -name obj.\* -o -name obj -exec rm \{\} \;
105
106if [ -z $BSDOBJDIR ] ; then
107    BSDOBJDIR=/usr/obj
108fi
109if [ -d $BSDOBJDIR ] ; then
110    rm -rf $BSDOBJDIR
111fi
112
113cd $BSDSRCDIR && make cleandir
114
115---cut here---
116
117Critical utilities:
118^^^^^^^^^^^^^^^^^^^
119	gnu/usr.bin/egcs
120	usr.bin/compile_et
121	usr.bin/make
122	usr.bin/yacc
123	usr.bin/lex
124	usr.sbin/config
125
126Other problems and possibly solutions:
127^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
128Symptom:Unreasonable compiler errors.
129Fix:	Rebuild gnu/usr.bin/egcs
130
131Symptom:Complaints involving a Makefile.
132Fix:	Make sure .mk files are up to date.
133	cd share/mk && make install
134Fix:	Rebuild usr.bin/make
135
136Symptom:Kernel `config' fails to configure any kernel, including GENERIC.
137Fix:	Rebuild usr.sbin/config
138
139Symptom:
140Fix:	Rebuild usr.bin/yacc
141
142Symptom:
143Fix:	Rebuild usr.bin/lex
144
145Symptom:
146Fix:	rm /usr/lib/libbfd.a
147
148Symptom:Obsolete intermediate files are used during compilation
149Fix:	Try the following sequence of commands in the directory in question.
150	make cleandir; rm `make print-objdir`; make cleandir; make obj
151	(If you built the tree without "make obj" in the past, obsolete files
152	may remain.  The command tries to clean everything up)
153
154Symptom:.../sysinst/run.c:xx: warning: initialization from incompatible pointer type
155Fix:	Rebuild and install usr.bin/menuc
156