<!DOCTYPE HTML PUBLIC "-//FreeBSD//DTD HTML 4.01 Transitional-Based Extension//EN" [
<!ENTITY base CDATA "../../">
<!ENTITY date "$FreeBSD$">
<!ENTITY title "FreeBSD GNOME Project: GNOME &gnomever; Upgrading FAQ">
<!ENTITY % navinclude.gnome "INCLUDE">
]>
<html>
  &header;

  <h2>Contents</h2>
    <ol>
    <li> <a href="#q1">What is new in GNOME &gnomever;?</a>
    <li> <a href="#q2">How do I upgrade to GNOME &gnomever;?</a>
    <li> <a href="#q3">Oops!  I ran <tt>portupgrade(1)</tt>!  What do I do?</a>
    <li> <a href="#q4">The upgrade failed; what do I do?</a>
    <li> <a href="#q5">List of known GNOME &gnomever; problems and their solutions</a>
    <li> <a href="#q6">I have found a bug; whom should I alert?</a>
    <li> <a href="#q7">I want the fame and glory of the FreeBSD GNOME team!  What
      can I do to participate?</a>
    </ol>

  <h2>Full Text</h2>
    <ol>
<!-- Q1 -->
      <li style="padding-bottom: 0.5em"><a name="q1"></a>
      <p><b>What is new in GNOME &gnomever;?</b></p>
<!-- A1 -->
      <p>Although the canonical summary of new features can be found at
        <a href="http://www.gnome.org/start/2.10/notes/rnwhatsnew.html">http://www.gnome.org/start/2.10/notes/rnwhatsnew.html</a>,
	some of the most exciting new features of GNOME &gnomever; are:</p>

      <ul>
	<li>FreeBSD support for CPU frequency monitoring, ACPI power
	  management, wireless signal strength monitoring for all
	  supported drivers, and disk read/write utilization
	<li>Better keyboard layout and feature control
	<li>Sleek selection of desktop backgrounds
	<li>Many new applications, applets, and UI enhancements
	<li>Extensive list of stability and speed increases
      </ul>

      </li>

<!-- Q2 -->
      <li style="padding-bottom: 0.5em"><a name="q2"></a>
      <p><b>How do I upgrade to GNOME &gnomever;?</b></p>
<!-- A2 -->
      <p><b><i>NOTE: Do <u>not</u> run <tt>portupgrade(1)</tt> to upgrade to GNOME &gnomever;!</i></b></p>

      <p>The simple answer is this:</p>

      <ol>
        <li><a href="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/cvsup.html">CVSup
	  your ports tree</a>.
	<li>Download the FreeBSD GNOME Project's <a href="http://www.FreeBSD.org/gnome/gnome_upgrade.sh">upgrade
	  script</a>.
	<li>Run the script as <tt>root</tt>.  Read a good-sized book.
      </ol>

      <p>More detailed instructions are as follows:</p>

      <ol>
        <li>CVSup your ports tree.

	<p>To build GNOME &gnomever;, you need to obtain the &gnomever; ports tree skeleton.  This is
	  most easily accomplished with CVSup.  Simply obtain the latest ports tree, and you are
	  ready to go.  After you have obtained the latest ports tree, <i>do not</i> run a typical
	  <tt>portupgrade(1)</tt>.</p>
	</li>

	<li>Obtain the upgrade script.

	<p>It is not possible to upgrade from GNOME &gnomeoldver; to GNOME &gnomever; by simply running
	  <tt>portupgrade(1)</tt>.  There are new dependencies, and ports will build out-of-order,
	  eventually causing the build to fail.</p>

	<p>To work around these problems, and to provide an update mechanism as simple as
	  <tt>portupgrade(1)</tt>, the FreeBSD GNOME team has produced a comprehensive upgrade script.
	  The script can be downloaded from:</p>

	<blockquote><a
	  href="http://www.FreeBSD.org/gnome/gnome_upgrade.sh">http://www.FreeBSD.org/gnome/gnome_upgrade.sh</a>
	</blockquote>

	<p>Simply download that script, and save it to disk.</p>
	</li>

	<li>Run the script.

	<p>Once you have the script downloaded, run, as <tt>root</tt>:</p>

	<pre>
# sh ./gnome_upgrade.sh
	</pre>
	<p>Hit <tt>ENTER</tt> to begin, answer any questions that pop up, and go watch an
	  <i>entire</i> Monty Python anthology.  Right after hitting <tt>ENTER</tt> at the beginning,
	  you will be given the path to a logfile.  By running:</p>

	  <pre>
$ tail -f /path/to/logfile
	  </pre>
	<p>you can watch the entire upgrade process as it unfolds.  It is hypnotic!</p>
	</li>
      </ol>
      </li>

<!-- Q3 -->
      <li style="padding-bottom: 0.5em"><a name="q3"></a>
      <p><b>Oops!  I ran <tt>portupgrade(1)</tt>!  What do I do?</b></p>
<!-- A3 -->
      <p>Do not worry; hope is not lost.  Running <tt>portupgrade(1)</tt> will cause the build
        to fail, but it will not cause any lasting damage to your ports tree, unless you have
	done something exceptionally creative.  Simply download the <tt>gnome_upgrade.sh</tt>
	script and run it, and pretend that you ran it in the first place.  Nobody needs to know
	that you did not read the directions first!</p>
      </li>

<!-- Q4 -->
      <li style="padding-bottom: 0.5em"><a name="q4"></a>
      <p><b>The upgrade failed; what do I do?</b></p>
<!-- A4 -->
      <p>Unfortunately, this is not only possible, it is highly probable.  There are many possible
        valid GNOME configurations, and even more invalid starting points.  If the script fails,
	follow the instructions in the error message to let the FreeBSD GNOME team know about the
	failure.</p>

      <p>The majority of build failures will be dependency-related issues.  One simple way to resolve
        the problem is to remove the offending port, re-run <tt>gnome_upgrade.sh</tt>, and then
	reinstall the port when the upgrade process is complete.  In
	order to avoid having to build everything again, you can pass
	the <tt>-restart</tt> flag to <tt>gnome_upgrade.sh</tt> to
	resume a failed build.</p>
      </li>

<!-- Q5 -->
      <li style="padding-bottom: 0.5em"><a name="q5"></a>
      <p><b>List of GNOME &gnomever; problems and their solutions</b></p>
<!-- A5 -->
      <p>Although GNOME &gnomever; is certainly the best release to date (of course), there are
	    a couple regressions that slipped in, both in the GNOME code and in its implementation
		within FreeBSD.  Some of the more visible issues are:</p>

		<ul>
	  <li>Changing the GTK theme can cause a few apps to crash. This issue is known  to the
            GNOME/Linux world, so it is not a FreeBSD-specific issue. You can ignore
			the error message, and click the "Restart" button to restart the
			crashed application when the dialog pops up. You should be fine after that.
	  <li>The KDE menu is missing some icons. KDE failed to follow the published
	        freedesktop.org standards, and places its icons in a non-standard
			location. GNOME 2.10 introduced a mass move towards complete compliance
			with freedesktop.org standards, so there's not much that can be done
			until KDE moves its default icons into a location that GNOME recognizes.

            <a href="http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html">http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html</a>
          <li><a href="http://bugzilla.gnome.org/show_bug.cgi?id=167934">
            #167934</a>: [gnome-menus] Any .desktop file in
            share/gnome/apps without a Categories entry will not work. This is due
			to a 
            LegacyDir bug that is supposed to be fixed in next release (2.10.1).
            The workaround is to add a Categories entry in the .desktop file in
			question.
	  <li>[gnome-session]: Options for shutting down or rebooting
	    will not appear on logout unless GDM is running on the
	    same machine.
	  <li>[multiload-applet]: The disk reads/writes monitor does
	    not work on -CURRENT.  A solution is currently being
	    sought.
          <li><a href="http://bugzilla.gnome.org/show_bug.cgi?id=137388">
            #137388</a>: [gnome-terminal] gnome-terminal has a problem
            with dynamic titles and vim (<b>UPDATE:</b> See this
	    <a
	    href="http://lists.freebsd.org/pipermail/freebsd-gnome/2004-May/006689.html">email</a>
	    for a workaround to this problem)
	  <li><a
	    href="http://bugzilla.ximian.com/show_bug.cgi?id=73375">#73375</a>:
	    [evolution] Evolution will crash when selecting a new
	    Server Type for an account with malloc debugging enabled.
	    This only affects -CURRENT users by default.  To disable
	    malloc debugging, run the command <tt>ln -sf aj
	    /etc/malloc.conf</tt> as root.
	  <li>GnomeVFS-2 now has native support for sftp methods.  Fully
	    non-interactive publickey authentication works on all versions
            of FreeBSD, but FreeBSD 5.X is required for password or
	    passphrase authentication.
		</ul>

      </li>

<!-- Q6 -->
      <li style="padding-bottom: 0.5em"><a name="q6"></a>
      <p><b>I have found a bug; whom should I alert?</b></p>
<!-- A6 -->
      <p>Please read the FreeBSD GNOME Project's
        <a href="http://www.FreeBSD.org/gnome/docs/bugging.html">documentation on reporting bugs</a>.
      </p>
      </li>

<!-- Q7 -->
      <li style="padding-bottom: 0.5em"><a name="q7"></a>
      <p><b>I want the fame and glory of being part of the FreeBSD GNOME team!
	    What can I do to participate?</b></p>
<!-- A7 -->
      <p>Please read our list of <a href="http://www.FreeBSD.org/gnome/docs/volunteer.html">ways
        to get involved</a>!
      </p>
      </li>
    </ol>

  &footer;
</body>
</html>
