This is the Sage VMware Virtual Appliance.  For more about Sage,
see http://www.sagemath.org


Requirements
============

This can be used on any operating system that supports VMware or the free
VMware player, for example Microsoft Windows.  Your computer must have at least
2.5 GB (!) of free disk space and at least 512 MB of RAM.


Installation
============

Installing Sage should take 15 to 20 minutes, less than 2 GB of hard drive
space, and be painless.

1. Download sage-vmware-x.y.zip

2. Extract it anywhere you want. This will take about 15 minutes despite
   anything Windows tells you.  Do *not* stop the extract halfway through
   and think Sage will still work.)

3. Make sure you have installed the free VMware program. See the following
   URL for more information: http://www.vmware.com/products/player/

4. Double click on sage_vmx in the sage-vmware-x.y directory to run Sage.


Using Sage
==========

1. When Sage starts up, click in the window (and possibly press
   Control-G on some computers), then type "notebook" at the prompt to
   start the Sage notebook server.

2. Now you can use Sage via your web browser from Windows 
   (it's best to use Firefox).

3. List available optional packages with the optional_packages()
   command and type install_package("exact package name") to install a
   package.  You do this from an input box in the notebook.

4. You can also login to Sage using ssh (e.g. with putty or Cygwin's
   openssh) by ssh'ing to the address that you use to view the
   notebook:

   login name: sage 
   password:   sage

5. If you have problems, get free tech support by subscribing to
   sage-support at

   http://groups.google.com/group/sage-support

   Or login to the IRC channgel #sagemath on freenode.net.


Troubleshooting
===============

You may experience some problems with installing Sage under Windows. Please
see the following email thread in the sage-support mailing list before
posting to sage-support:

* http://groups.google.com/group/sage-support/browse_thread/thread/c2c02bc48d41f61f


How to be a Sage developer (more advanced)
==========================================

Some Unix familiarity is assumed below.  If you've never used anything
but Windows, some of this won't make sense. 
 
1. Install an SSH client, e.g. putty. 

2. ssh to the same IP address as the Sage Notebook.  For example, if when you 
   run notebook it says:

     Open Firefox to the address http://172.16.248.137
     It may take up to about 10 seconds for the server to start. Press refresh.
     (Click here and press control-C twice to stop the notebook server)

   then you should SSH to 172.16.248.137.  Use the login name "sage" and the
   password "sage". 

3. To have permission to change files, become the root user by typing
   "sudo su":

     sage@sage:~$ sudo su
     root@sage:/home/sage# 

4. Change to the SAGE_ROOT directory:

     root@sage:/home/sage# cd /usr/local/sage
     root@sage:/usr/local/sage# 

5. To actually edit files, you'll perhaps want to install the editor
   of your choice.  For example, to install Emacs do this:

     root@sage:/usr/local/sage# apt-get install emacs
      ...

6. Now type, for example,

     root@sage:/usr/local/sage# cd devel/sage/sage/rings/
     root@sage:/usr/local/sage/devel/sage/sage/rings# emacs arith.py
     [edit the file]

7. Save the file and type "sage -br" to build the changes and install them.

     root@sage:/usr/local/sage/devel/sage/sage/rings# sage -br
     ----------------------------------------------------------
     sage: Building and installing modified SAGE library files.
     ...
     ----------------------------------------------------------------------
     | SAGE Version 3.0, Release Date: .........                       |
     | Type notebook() for the GUI, and license() for information.        |
     ----------------------------------------------------------------------

     sage: 

8. Try out your modified Sage!

9. Other options, for those who know a lot about Linux, etc.:

     * Install an X server in Windows, e.g. via Cygwin, and window back emacs.
     * Install a window manager into the Sage virtual machine and use it.
     * Upgrade to the non-free VMware workstation and use a shared
       filesystem (untested).

10. Upgrading: Type "sage -upgrade" at the command prompt:

      root@sage:~# sage -upgrade
      ...
      takes about 20 minutes 

    This *will* merge your changes to /usr/local/sage/devel/ with the 
    latest version of Sage and build everything. 

    WARNING: This will use up more disk space and is *not* guaranteed to
    result in a working upgraded Sage installation.

11. To save changes and share them with others, be sure to read the
    chapter "Walking Through the Development Process" in the Sage Developer's
    Guide at 

      http://www.sagemath.org/doc/developer/walk_through.html

    Once you have saved a particular branch bundle foo.hg, you need to get
    it out of the VMware virtual machine somehow.  Options include:

    1. Install a program such as http://winscp.net which will allow
       you to easily drag and drop windows between the VMware Sage virtual
       machine and your Windows desktop.  Be sure to connect to the IP
       address using the same login name and password as you used for 
       SSH before. 

    2. Type "scp foo.hg username@computer" at the command prompt, e.g.

       root@sage #   scp foo.hg wstein@math.washington.edu: