1 # -------+---------+---------+---------+---------+---------+---------+---------+
3 The FreeBSD/sparc64 port has now changed time_t from 32-bits to 64-bits.
4 This file explains the exact steps that users should follow to update their
5 sparc64 systems for this change. People running FreeBSD on other types of
6 hardware, such as CPU's from Intel or AMD, can ignore this file. For now,
7 this change is only happening for people running FreeBSD on Sparc hardware.
9 # -------+---------+---------+---------+---------+---------+---------+---------+
10 # Copyright (c) 2004 - Garance Alistair Drosehn <gad@FreeBSD.org>.
12 # All rights reserved.
14 # Redistribution, publication, translation and use, with or without
15 # modification, in full or in part, in any form or format of this
16 # document are permitted without further permission from the author.
18 # THIS DOCUMENT IS PROVIDED BY GARANCE DROSEHN ``AS IS'' AND ANY EXPRESS
19 # OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
20 # WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
21 # DISCLAIMED. IN NO EVENT SHALL GARANCE DROSEHN BE LIABLE FOR ANY DIRECT,
22 # INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
23 # (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
24 # SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 # HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
26 # STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
27 # IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28 # POSSIBILITY OF SUCH DAMAGE.
30 # -------+---------+---------+---------+---------+---------+---------+---------+
32 # -------+---------+---------+---------+---------+---------+---------+---------+
34 If you are in too much of a hurry to read this file, then this is not the
35 time for you to upgrade to a 64-bit time_t. Period. Stick with a system
36 using 32-bit time_t until you have plenty of time to perform an upgrade.
38 This statement is true even if you have performed a thousand system upgrades
39 in the past, and you are certain that you know everything there is to know
40 about upgrades. This upgrade *will* take you more time than previous system
41 upgrades, simply because you must recompile at least some of your ports after
42 upgrading the base system.
44 Do not start this update unless you have the extra time.
46 As of March 10th, the official value for time_t on sparc64 has changed to
47 be 64-bits. If you really must build system with 32-bit time_t's, then it
48 would be best to stick with a snapshot of current from before March 10th.
49 With src snapshots after that point, there will soon be ports which assume
50 you have a 64-bit time_t based on the value of __FreeBSD_version.
52 If you are ready to upgrade, then *READ THIS ENTIRE DOCUMENT* at least
53 once before starting the upgrade.
55 # -------+---------+---------+---------+---------+---------+---------+---------+
57 This is a major change. This change will *not* be backwards-compatible.
58 Any programs which call system-routines for handling time-values will
59 have to be recompiled after this change is made.
61 Because this change is not backwards-compatible, it is important that
62 the following steps be used when upgrading the system. "Shortcuts" that
63 have worked for EVERY SINGLE UPGRADE YOU HAVE EVER DONE IN YOUR LIFE are
64 probably irrelevant. This change is more disruptive than most of the
65 changes which are normally done on freebsd.
67 These steps are designed to minimize the chance of you running into any
68 trouble. We can not guarantee that these steps will avoid all possible
69 problems, but if you ignore these steps you are very likely to run into
70 some very painful and time-consuming headaches when upgrading.
72 Step Pre-1: Update to a recent snapshot of -current, and first build
73 that as a system with 32-bit time_t. To do this, edit
74 the file /usr/src/sys/sparc64/include/_types.h
76 typedef __int64_t __time_t; /* time()... */
77 and change '__int64_t' to '__int32_t'
78 Step Pre-2: Install that system, using whatever steps you normally
79 use, and make sure that installation seems to work okay.
80 Step Pre-3: While still running that 32-bit time_t system, it would
81 probably be a good idea to cvsup your ports tree, and
82 then upgrade portupgrade (if you use it) and upgrade any
83 shells that you use. Eg:
84 portupgrade -Rr -f ruby portupgrade
85 portupgrade -Rr -f bash
86 That way you know you have the latest versions, and you
87 will also know you have the most-recent distfiles on
90 Step Pre-4: For sparc64 machines which need DHCP:
91 The 'dhclient' in the base system is known to be unreliable
92 on a system which is upgraded to 64-bit time_t's. It may
93 work for you, but it probably will not.
94 As of March 10th 2004, we have no fix for that.
95 However, the net/isc-dhcp3-client port does seem to work.
96 IF your machine needs DHCP, then you should probably install
97 that port and make sure you can get it working *before* you
98 make the change to use 64-bit time_t's.
100 After you have built and installed that src-snapshot with 32-bit time_t's,
101 edit the file /usr/src/sys/sparc64/include/_types.h
103 typedef __int32_t __time_t; /* time()... */
104 and change '__int32_t' back to '__int64_t'
106 For best results, do NOT make any other changes. Do NOT cvsup the
107 source tree trying to pick up any other changes. At this point you
108 know that you have a source tree that does work for your system, so
109 stick with that source tree (except for making the above 1-line
112 At one point in my testing, I did do a 'cvsup' which just happened
113 to pull in one bad commit that broke 'make buildworld', and a second
114 bad commit that broke 'make installworld'. Believe me, you REALLY
115 REALLY do *not* want to risk problems like that!
117 I am not suggesting that you have to do two whole buildworld/
118 installworld cycles in a single day. You could easily wait a few
119 days, or even a week between them. What I am suggesting is that
120 you should not 'cvsup' your sources inbetween the two buildworlds.
122 And then follow these steps to build and install the 64-bit time_t system:
125 make cleanworld #- 2. or 'rm -Rf /usr/obj/usr/src/*'
126 make buildworld #- 3.
127 make buildkernel #- 4. Add KERNCONF if you usually do.
128 NEWSPARC_TIMETYPE=__int64_t #- 5. (Used by a safety-check done
129 export NEWSPARC_TIMETYPE #- 5a. by installkernel)
130 make installkernel #- 6. Add KERNCONF if you usually do.
133 # - - A section required for installs over NFS-mounts - - #
134 ifconfig -a #- NFS 8a. See note below.
135 shutdown now #- NFS 8b. NOT 'shutdown -r now'
136 cd /usr/src #- NFS 8c.
137 sh installworld_oldk #- NFS 8d. See note below.
138 # - - End of this section for NFS-mounts - - #
140 reboot #- 9. MUST go into single-user mode
142 For many upgrades, it is true that you can "cheat" at this point, and
143 get away without actually going into single-user mode straight from
144 the reboot. But for this upgrade, you REALLY MUST start up straight
145 into single user mode. So, reboot the machine, type a space (or
146 anything other than 'Enter') when the boot-loader is counting down.
149 boot -s #- 10. (command to boot-loader)
151 The system will ask you if you want to use /bin/sh or some other shell.
152 For this upgrade, just hit enter, even if you usually prefer like some
153 other shell instead of /bin/sh.
156 # - - A section required for installs over NFS-mounts - - #
157 PATH=/boot/kernel/bin:$PATH #- NFS 12.
158 # - - End of this section for NFS-mounts - - #
159 mount -a -t ufs #- 13.
161 # - - A section required for installs over NFS-mounts - - #
162 ifconfig hme0 inet .... #- NFS 15a. See note below.
163 mount_nfs host:srcdir /usr/src #- NFS 15b. See note below.
164 mount_nfs host:objdir /usr/obj #- NFS 15c.
165 # - - End of this section for NFS-mounts - - #
167 sh installworld_newk #- 17. Might want to add -S
169 rm -f /var/db/dhclient.leases #- 19. If this host uses DHCP
172 At this point, you should be up-and-running on a system that has 64-bit
173 values for time_t. You will have to rebuild anything which depends on
174 time_t. Later in this file is a suggested order for upgrading ports.
176 If you have a lot of ports which start up daemons or do other processing
177 at system-startup, then you might want to have this reboot also go into
178 single-user mode for upgrading all of the ports. In my case, I've always
179 done a standard reboot at this point and did not run into problems, but
180 then I only have 25 ports installed on my SPARC64 system.
182 Aside: It is slightly more reasonable to use the 'reboot' command, although
183 you may be more familar with using 'shutdown -r now'. The shutdown command
184 just turns around and executes '/sbin/reboot', and with this upgrade it is
185 best to avoid such redirection.
187 # -------+---------+--------- Notes on the above -------+---------+---------+
189 General notes on NFS issues:
191 For this upgrade to 64-bit time_t's, the change is so disruptive that I
192 couldn't get NFS-mounts to work if I booted a "32-bit time_t system"
193 (ie: 32-bit versions of /bin, /sbin, /lib, ...) on a 64-bit kernel. So,
194 I added the installworld_oldk script. This script does two things:
195 1) Creates a mini-/bin inside /boot/kernel.
196 2) Does a minimal installworld (while still on the old kernel),
197 thus making it possible for NFS-mounts to work when you reboot.
199 The first half is a step that would be perfectly safe to do, for any
200 upgrade (including non-NFS ones), at any time. It is a generally safe
201 and interesting idea, although it really should be implemented as an
202 official target in /usr/src/Makefile to be done right.
204 The second half would USUALLY be a bad idea to do, but I think it's the
205 only way I can get this specific upgrade to work for people that install
206 from NFS-mounted directories. It is bad because you are clobbering parts
207 of your system even though (in the usual case) you would not know that
208 the new kernel actually works on your system. It also does not do a
209 full-install, so you end up booting into a system which is part old-
210 world, and part new-world. It looks like we can get away with that for
211 this upgrade, but the tactic would be too risky for "standard upgrades".
213 These instructions assume that you are already familiar with how to do
214 installations over NFS-mounted partitions. If you are not, you might
215 want to read other references, such as 'man development'.
217 Notes on step NFS 8a: ifconfig -a
219 This shows to the configuration of all your ethernet interfaces. Write
220 down the IP address and netmask of your main interface. This is
221 particularly important if the machine obtains its address via DHCP.
222 You will not be running dhclient after the reboot in step 8, so just
223 re-use the IP address that the machine is using for the present reboot.
225 Notes on step NFS 8b: shutdown now
227 This will drop you into single-user mode, without rebooting. It
228 will ask if you want to use /bin/sh for your shell. You do.
230 Notes on step NFS 8d: sh installworld_oldk
232 Note that this script only installs *part* of the new world. You will
233 still have to reboot into single-user mode and do the full installworld.
234 The installworld_oldk script will ask you if you want to build a
235 mini-/bin. For this upgrade, you should say "yes".
237 Notes on step NFS 15a:
238 On my Ultra-10, I have the 'hme0' device as my ethernet card. The output
239 of 'ifconfig -a' (from step 'NFS 7a') included the lines:
241 hme0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
242 inet 192.168.1.18 netmask 0xffffffe0 broadcast 192.168.1.31
244 So for this step, I typed in the command:
245 ifconfig hme0 inet 192.168.1.18 netmask 0xffffff00
247 Notes on step NFS 15b: mount_nfs
249 At this step, you may need to specify the host as an IP address instead
250 of a hostname, because the machine will only be able to resolve hostnames
251 that are in /etc/hosts.
253 In my case, I found it easier to create a source file ahead of time
254 which included the ifconfig and mount_nfs commands that I knew I would
255 need, and then I just sourced that file after rebooting into single user
256 mode. If you made such a source file and put it in your root partition,
257 perhaps under /boot, then that file could also include all of the steps
260 Also, it is best use the 'mount_nfs' command, instead of 'mount -t nfs'.
261 If you use the 'mount' command for NFS mounts, it will turn around and
262 directly execute /sbin/mount_nfs, and that is not desirable in this case.
264 Notes on step 17: sh installworld_newk
266 This script will do some setup work, and then ask you if want it to run
267 'make installworld'. Most people should just answer "y" (yes) to that
268 prompt. You can avoid the prompt by including "-y" or "-n" on the
269 command. If you say "n" (no), then it will tell you what commands
270 you must type to do the actual installworld.
272 The script also recognizes a "-S" parameter, which causes it to use
273 symlinks instead of making copies of programs used by the installation
274 process. This option will cause less filespace to be used up in /tmp,
275 but it might be slower in some cases (especially for installs using
276 an NFS-mounted directory for /usr/obj).
278 Both this script and the installworld_oldk script also recognize a "-M"
279 option. This option causes the script to use the absolute minimum PATH
280 setting that "should" be needed to complete an install. This option is
281 mainly just for debugging the scripts, though. If you request the
282 minimum PATH, and some important file was NOT properly copied, then the
283 installworld will immediately die at that point. This might be painful.
284 Without "-M", the same oversight would mean that you will run the wrong
285 *version* of the command, but that older version might actually work
286 perfectly fine. I did all my testing with "-M" to make sure I had
287 found all important programs, but there is probably no advantage for
288 using it for standard system upgrades. Also, if there are no important
289 files overlooked, then "-M" will not make any difference at all.
291 # -------+---------+---------+ Upgrading Ports +---------+---------+---------+
293 Similar to the recommendation for the upgrading the system, I suggest that
294 you do not 'cvsup' your local copy of the ports collection before trying to
295 rebuild everything for 64-bit time_t. For one thing, you will have a cvsup
296 compiled for 32-bTT (32-bit time_t's), and that will not work well on a
297 system which is using 64-bTT. You might find that you have to 'cvsup' for
298 some ports, but you will need to get a 64-bTT version of cvsup before you
301 One tactic to use for upgrading ports is to rebuild your already-installed
302 ports one-at-a-time. If you want to do that, and if you use portupgrade
303 to upgrade your ports, then I suggest the first thing you should do is:
305 portupgrade -Rr -f ruby portupgrade #- Ports 1.
306 Aside: if you get an error about the "ruby-rdoc" port,
307 then enter: pkg_deinstall ruby-rdoc
308 and repeat the original command.
309 portupgrade -Rr -f bash #- Ports 2.
310 If you have 'bash' installed, or include any other shells
311 which you have installed from the ports collection. If
312 your session is *using* one of these shells, then logout
313 and log back in after recompiling that shell.
314 portupgrade -Rr -f ezm3 cvsup-without-gui #- Ports 3 (maybe).
315 If you want to rebuild a 64-bit time_t version of cvsup.
316 Note: ezm3 (modula-3) needs a patch to work correctly after the
317 change to 64-BTT. That fix has not been commited to the port
318 yet [as of Mar 10th], but hopefully it will be commited soon.
320 There are pre-built packages available for ezm3 and cvsup-without-gui on
321 the new 64-bTT systems. This ezm3 package *does* include the necessarily
322 patch. These files are available on the standard ftp servers for FreeBSD.
323 If you have previous versions installed, then remove them with:
327 If you get warnings about "unable to completely remove" some
328 lib/m3 directories when deleting ezm3, then also enter:
329 rm -rf /usr/local/lib/m3
331 You can install the new packages with:
333 pkg_add ftp://ftp3.FreeBSD.org/pub/FreeBSD/ports/local-distfiles/gad/ez...
334 pkg_add ftp://ftp3.FreeBSD.org/pub/FreeBSD/ports/local-distfiles/gad/cv...
335 Replacing "ez..." with "ezm3-64btt-1.1_1.tbz" and "cv..."
336 with "cvsup-without-gui-64btt-16.1h.tbz". You can also use
337 some other standard ftp server, instead of ftp3.FreeBSD.org.
339 "Now look over all the other ports you have installed, and
340 re-compile everything that probably needs to be recompiled".
342 If you are going to do it piecemeal, the next ports to force-rebuild would
343 probably be languages like perl and python, if you have them installed.
344 After that, force-rebuild the ports like autoconf and automake, if you
345 have them installed. Or you might want to play it safe at this point,
346 and simply recompile *every* port that you have installed.
348 A different tactic to use for ports is to remove *all* ports before you
349 do the installkernel/installworld step (while you're still on a 32-bTT
350 system). Then, once you're up on the 64-bTT system, start making them
351 one-by-one. If you follow this tactic, you might want to save the output
352 of a 'pkg_info' command before you start removing ports.
354 # -------+---------+---------+---------+---------+---------+---------+---------+
356 If you run into problems when making this change, please report them to
357 the mailing list freebsd-sparc64@FreeBSD.org .
359 # -------+---------+---------+---------+---------+---------+---------+---------+
360 # Notice that the following command can be useful in some settings:
361 grep '#\- ' UPDATING.64BTT