Commit the first set of files for changing time_t on freebsd/sparc64

from a 32-bit value to a 64-bit value.  This commit does not actually
change anything.  It merely provides instructions, scripts, and a safety
measure in Makefile.inc1 for people who want to make the change.

The real change to 64-bit time_t's on sparc64 is scheduled to happen
on March 10th, assuming that so major problems are found between now
and then by early-adopters.

Reviewed by:	freebsd-sparc64

1 files changed, 361 insertions, 0 deletions

diff --git a/UPDATING.64BTT b/UPDATING.64BTT
new file mode 100644
index 0000000..bad7cea
--- /dev/null
+++ b/UPDATING.64BTT
@@ -0,0 +1,361 @@
+# -------+---------+---------+---------+---------+---------+---------+---------+
+
+   The FreeBSD/sparc64 port is going to change time_t from 32-bits to 64-bits.
+   This file explains the exact steps that users should follow to update their
+   sparc64 systems for this change.  People running FreeBSD on other types of
+   hardware, such as CPU's from Intel or AMD, can ignore this file.  For now,
+   this change is only happening for people running FreeBSD on Sparc hardware. 
+
+# -------+---------+---------+---------+---------+---------+---------+---------+
+# Copyright (c) 2004  - Garance Alistair Drosehn <gad@FreeBSD.org>.
+#
+# All rights reserved.
+#
+#  Redistribution, publication, translation and use, with or without     
+#  modification, in full or in part, in any form or format of this      
+#  document are permitted without further permission from the author.
+#
+#  THIS DOCUMENT IS PROVIDED BY GARANCE DROSEHN ``AS IS'' AND ANY EXPRESS
+#  OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED     
+#  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+#  DISCLAIMED.  IN NO EVENT SHALL GARANCE DROSEHN BE LIABLE FOR ANY DIRECT,
+#  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+#  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+#  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+#  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+#  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
+#  IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+#  POSSIBILITY OF SUCH DAMAGE.
+#
+# -------+---------+---------+---------+---------+---------+---------+---------+
+# $FreeBSD$
+# -------+---------+---------+---------+---------+---------+---------+---------+
+
+If you are in too much of a hurry to read this file, then this is not the
+time for you to upgrade to a 64-bit time_t.  Period.  Stick with a system
+using 32-bit time_t until you have plenty of time to perform an upgrade.
+
+This statement is true even if you have performed a thousand system upgrades
+in the past, and you are certain that you know everything there is to know
+about upgrades.  This upgrade *will* take you more time than previous system
+upgrades, simply because you must recompile at least some of your ports after
+upgrading the base system.
+
+Do not start this update unless you have the extra time.
+
+* READ THIS ENTIRE DOCUMENT at least once before starting the upgrade. *
+
+This is a major change.  This change will *not* be backwards-compatible.
+Any programs which call system-routines for handling time-values will
+have to be recompiled after this change is made.
+
+Because this change is not backwards-compatible, it is important that
+the following steps be used when upgrading the system.  "Shortcuts" that
+have worked for EVERY SINGLE UPGRADE YOU HAVE EVER DONE IN YOUR LIFE are
+probably irrelevant.  This change is more disruptive than most of the
+changes which are normally done on freebsd.
+
+These steps are designed to minimize the chance of you running into any
+trouble.  We can not guarantee that these steps will avoid all possible
+problems, but if you ignore these steps you are very likely to run into
+some very painful and time-consuming headaches when upgrading.
+
+Step Pre-1:  Update to a recent snapshot of -current, keeping it as
+             a system with 32-bit time_t.
+Step Pre-2:  Install that system, using whatever steps you normally
+             use, and make sure that installation seems to work okay.
+Step Pre-3:  While still running that 32-bit time_t system, it would
+             probably be a good idea to cvsup your ports tree, and
+             then upgrade portupgrade (if you use it) and upgrade any
+             shells that you use.  Eg:
+                  portupgrade -Rr -f ruby portupgrade
+                  portupgrade -Rr -f bash
+             That way you know you have the latest versions, and you
+             will also know you have the most-recent distfiles on
+             your machine.
+
+Step Pre-4:  For sparc64 machines which need DHCP:
+             The 'dhclient' in the base system is known to be unreliable
+	     on a system which is upgraded to 64-bit time_t's.  It may
+	     work for you, but it probably will not.
+	     As of March 3rd 2004, we have no fix for that.
+	     However, the net/isc-dhcp3-client port does seem to work.
+	     IF your machine needs DHCP, then you should probably install
+	     that port and make sure you can get it working *before* you
+	     make the change to use 64-bit time_t's.
+
+<instructions for early-adopters>
+     edit the file  /usr/src/sys/sparc64/include/_types.h 
+     find the line:
+        typedef	__int32_t	__time_t;	/* time()... */
+     and change '__int32_t' to '__int64_t'
+
+     For best results, do NOT make any other changes.  Do NOT cvsup the
+     source tree trying to pick up any other changes.  At this point you
+     know that you have a source tree that does work for your system, so
+     stick with that source tree (except for making the above 1-line
+     change, of course).
+
+     At one point in my testing, I did do a 'cvsup' which just happened
+     to pull in one bad commit that broke 'make buildworld', and a second
+     bad commit that broke 'make installworld'.  Believe me, you REALLY
+     REALLY do *not* want to risk problems like that!
+
+     I am not suggesting that you have to do two whole buildworld/
+     installworld cycles in a single day.  You could easily wait a few
+     days, or even a week between them.  What I am suggesting is that
+      you should not 'cvsup' your sources inbetween the two buildworlds.
+</instructions for early-adopters>
+
+    cd /usr/src                   #-  1.
+    make cleanworld               #-  2.  or 'rm -Rf /usr/obj/usr/src/*'
+    make buildworld               #-  3.
+    make buildkernel              #-  4.  Add KERNCONF if you usually do.
+    NEWSPARC_TIMETYPE=__int64_t   #-  5.  (Used by a safety-check done
+    export NEWSPARC_TIMETYPE      #-  5a.   by installkernel)
+    make installkernel            #-  6.  Add KERNCONF if you usually do.
+    mergemaster -p                #-  7.
+
+        # - - A section required for installs over NFS-mounts  - - #
+    ifconfig -a                   #-  NFS 8a.       See note below.
+    shutdown now                  #-  NFS 8b.  NOT 'shutdown -r now'
+    cd /usr/src                   #-  NFS 8c.
+    ./installworld_oldk           #-  NFS 8d.       See note below.
+        # - -        End of this section for NFS-mounts        - - #
+
+    reboot                        #-  9.  MUST go into single-user mode
+
+For many upgrades, it is true that you can "cheat" at this point, and
+get away without actually going into single-user mode straight from
+the reboot.  But for this upgrade, you REALLY MUST start up straight
+into single user mode.  So, reboot the machine, type a space (or
+anything other than 'Enter') when the boot-loader is counting down.
+And then:
+
+      boot -s                            #- 10.  (command to boot-loader)
+
+The system will ask you if you want to use /bin/sh or some other shell.
+For this upgrade, just hit enter, even if you usually prefer like some
+other shell instead of /bin/sh.
+
+      fsck -p                            #- 11.
+         # - - A section required for installs over NFS-mounts  - - #
+      PATH=/boot/kernel/bin:$PATH        #- NFS 12.
+         # - -        End of this section for NFS-mounts        - - #
+      mount -a -t ufs                    #- 13.
+      swapon -a                          #- 14.
+         # - - A section required for installs over NFS-mounts  - - #
+      ifconfig hme0 inet ....            #- NFS 15a.   See note below.
+      mount_nfs host:srcdir /usr/src     #- NFS 15b.   See note below.
+      mount_nfs host:objdir /usr/obj     #- NFS 15c.
+         # - -        End of this section for NFS-mounts        - - #
+      cd /usr/src                        #- 16.
+      ./installworld_newk                #- 17.  Might want to add -S
+      mergemaster                        #- 18.
+      rm -f /var/db/dhclient.leases      #- 19.  If this host uses DHCP
+      reboot                             #- 20.
+
+At this point, you should be up-and-running on a system that has 64-bit
+values for time_t.  You will have to rebuild anything which depends on
+time_t.  Later in this file is a suggested order for upgrading ports.
+
+If you have a lot of ports which start up daemons or do other processing
+at system-startup, then you might want to have this reboot also go into
+single-user mode for upgrading all of the ports.  In my case, I've always
+done a standard reboot at this point and did not run into problems, but
+then I only have 25 ports installed on my SPARC64 system.
+
+Aside: It is slightly more reasonable to use the 'reboot' command, although
+you may be more familar with using 'shutdown -r now'.  The shutdown command
+just turns around and executes '/sbin/reboot', and with this upgrade it is
+best to avoid such redirection.
+
+# -------+---------+---------  Notes on the above   -------+---------+---------+
+
+General notes on NFS issues:
+
+  For this upgrade to 64-bit time_t's, the change is so disruptive that I
+  couldn't get NFS-mounts to work if I booted a "32-bit time_t system"
+  (ie: 32-bit versions of /bin, /sbin, /lib, ...) on a 64-bit kernel.  So,
+  I added the installworld_oldk script.  This script does two things:
+     1)  Creates a mini-/bin inside /boot/kernel.
+     2)  Does a minimal installworld (while still on the old kernel),
+         thus making it possible for NFS-mounts to work when you reboot.
+
+  The first half is a step that would be perfectly safe to do, for any
+  upgrade (including non-NFS ones), at any time.  It is a generally safe
+  and interesting idea, although it really should be implemented as an
+  official target in /usr/src/Makefile to be done right.
+
+  The second half would USUALLY be a bad idea to do, but I think it's the
+  only way I can get this specific upgrade to work for people that install
+  from NFS-mounted directories.  It is bad because you are clobbering parts
+  of your system even though (in the usual case) you would not know that
+  the new kernel actually works on your system.  It also does not do a
+  full-install, so you end up booting into a system which is part old-
+  world, and part new-world.  It looks like we can get away with that for
+  this upgrade, but the tactic would be too risky for "standard upgrades".
+
+  These instructions assume that you are already familiar with how to do
+  installations over NFS-mounted partitions.  If you are not, you might
+  want to read other references, such as 'man development'.
+
+Notes on step NFS 8a:     ifconfig -a
+
+  This shows to the configuration of all your ethernet interfaces.  Write
+  down the IP address and netmask of your main interface.  This is
+  particularly important if the machine obtains its address via DHCP.
+  You will not be running dhclient after the reboot in step 8, so just
+  re-use the IP address that the machine is using for the present reboot.
+
+Notes on step NFS 8b:     shutdown now
+
+  This will drop you into single-user mode, without rebooting.  It
+  will ask if you want to use /bin/sh for your shell.  You do.
+
+Notes on step NFS 8d:     installworld_oldk
+
+  Note that this script only installs *part* of the new world.  You will
+  still have to reboot into single-user mode and do the full installworld.
+  The installworld_oldk script will ask you if you want to build a
+  mini-/bin.  For this upgrade, you should say "yes".
+
+Notes on step NFS 15a:
+  On my Ultra-10, I have the 'hme0' device as my ethernet card.  The output
+  of 'ifconfig -a' (from step 'NFS 7a') included the lines:
+
+      hme0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
+            inet 192.168.1.18 netmask 0xffffffe0 broadcast 192.168.1.31
+
+  So for this step, I typed in the command:
+      ifconfig hme0 inet 192.168.1.18 netmask 0xffffff00
+
+Notes on step NFS 15b:    mount_nfs 
+
+  At this step, you may need to specify the host as an IP address instead
+  of a hostname, because the machine will only be able to resolve hostnames
+  that are in /etc/hosts.
+
+  In my case,  I found it easier to create a source file ahead of time
+  which included the ifconfig and mount_nfs commands that I knew I would
+  need, and then I just sourced that file after rebooting into single user
+  mode.  If you made such a source file and put it in your root partition,
+  perhaps under /boot, then that file could also include all of the steps
+  from 11 through 15c.
+
+  Also, it is best use the 'mount_nfs' command, instead of 'mount -t nfs'.
+  If you use the 'mount' command for NFS mounts, it will turn around and
+  directly execute /sbin/mount_nfs, and that is not desirable in this case.
+
+Notes on step 17:         ./installworld_newk 
+
+  This script will do some setup work, and then ask you if want it to run
+  'make installworld'.  Most people should just answer "y" (yes) to that
+  prompt.  You can avoid the prompt by including "-y" or "-n" on the
+  command.  If you say "n" (no), then it will tell you what commands
+  you must type to do the actual installworld.
+
+  The script also recognizes a "-S" parameter, which causes it to use
+  symlinks instead of making copies of programs used by the installation
+  process.  This option will cause less filespace to be used up in /tmp,
+  but it might be slower in some cases (especially for installs using
+  an NFS-mounted directory for /usr/obj).
+
+  Both this script and the installworld_oldk script also recognize a "-M"
+  option.  This option causes the script to use the absolute minimum PATH
+  setting that "should" be needed to complete an install.  This option is
+  mainly just for debugging the scripts, though.  If you request the
+  minimum PATH, and some important file was NOT properly copied, then the
+  installworld will immediately die at that point. This might be painful.
+  Without "-M", the same oversight would mean that you will run the wrong
+  *version* of the command, but that older version might actually work
+  perfectly fine.  I did all my testing with "-M" to make sure I had
+  found all important programs, but there is probably no advantage for
+  using it for standard system upgrades.  Also, if there are no important
+  files overlooked, then "-M" will not make any difference at all.
+
+# -------+---------+---------+  Upgrading Ports  +---------+---------+---------+
+
+Similar to the recommendation for the upgrading the system, I suggest that
+you do not 'cvsup' your local copy of the ports collection before trying to
+rebuild everything for 64-bit time_t.  For one thing, you will have a cvsup
+compiled for 32-bTT (32-bit time_t's), and that will not work well on a
+system which is using 64-bTT.  You might find that you have to 'cvsup' for
+some ports, but you will need to get a 64-bTT version of cvsup before you
+can do that. 
+
+One tactic to use for upgrading ports is to rebuild your already-installed
+ports one-at-a-time.  If you want to do that, and if you use portupgrade
+to upgrade your ports, then I suggest the first thing you should do is:
+
+    portupgrade -Rr -f ruby portupgrade          #- Ports 1.
+        Aside: if you get an error about the "ruby-rdoc" port,
+        then enter:    pkg_deinstall ruby-rdoc
+        and repeat the original command.
+    portupgrade -Rr -f bash                      #- Ports 2.
+        If you have 'bash' installed, or include any other shells
+        which you have installed from the ports collection.  If
+        your session is *using* one of these shells, then logout
+        and log back in after recompiling that shell.
+    portupgrade -Rr -f ezm3 cvsup-without-gui    #- Ports 3 (maybe).
+        If you want to rebuild a 64-bit time_t version of cvsup.
+	Note: ezm3 (modula-3) needs a patch to work correctly after
+	the change to 64-BTT.  That fix has not been commited to the
+	port yet [as of Mar 3rd], but it should be commited soon.
+
+There are pre-built packages available for ezm3 and cvsup-without-gui on
+the new 64-bTT systems.  This ezm3 package *does* include the necessarily
+patch.  These files are available on the standard ftp servers for FreeBSD.
+If you have previous versions installed, then remove them with:
+
+    pkg_delete cvsup\*
+    pkg_delete ezm3\*
+	If you get warnings about "unable to completely remove" some
+	lib/m3 directories when deleting ezm3, then also enter:
+    rm -rf /usr/local/lib/m3
+
+You can install the new packages with:
+
+    pkg_add ftp://ftp3.FreeBSD.org/pub/FreeBSD/ports/local-distfiles/gad/ez...
+    pkg_add ftp://ftp3.FreeBSD.org/pub/FreeBSD/ports/local-distfiles/gad/cv...
+	Replacing "ez..." with "ezm3-64btt-1.1_1.tbz" and "cv..."
+	with "cvsup-without-gui-64btt-16.1h.tbz".  You can also use
+	some other standard ftp server, instead of ftp3.FreeBSD.org.
+
+    "Now look over all the other ports you have installed, and
+    re-compile everything that probably needs to be recompiled".
+
+If you are going to do it piecemeal, the next ports to force-recompile
+would probably be languages like perl and python, if you have them
+installed.  Or you might want to play it safe at this point, and simply
+recompile *every* port that you have installed.
+
+A different tactic to use for ports is to remove *all* ports before you
+do the installkernel/installworld step (while you're still on a 32-bTT
+system).  Then, once you're up on the 64-bTT system, start making them
+one-by-one.  If you follow this tactic, you might want to save the output
+of a 'pkg_info' command before you start removing ports.
+
+# -------+---------+---------+---------+---------+---------+---------+---------+
+
+If you run into problems when making this change, please report them to
+the mailing list freebsd-sparc64@FreeBSD.org .
+
+# -------+---------+---------+---------+---------+---------+---------+---------+
+
+<Final notes for early-adopters>
+    For people who are helping out by testing these instructions, note
+    that once you make this change, you must remember to KEEP changing
+    __time_t in _types.h after every time you 'cvs update' or cvsup
+    your /usr/src tree.  If you forget, and end up building a world
+    with 32-bit time_t's, you will probably have a very very bad day.
+    Once this change is committed for real (which is scheduled for
+    March 10th), you will not need to care about this issue as much.
+
+    Also, a change has been committed to /usr/src/Makefile.inc1 which
+    does try to protect you from making this mistake.
+</final notes for early-adopters>
+
+# -------+---------+---------+---------+---------+---------+---------+---------+
+#  Notice that the following command can be useful in some settings:
+               grep '#\- ' UPDATING.64BTT