Differences between revisions 1 and 44 (spanning 43 versions)
⇤ ← Revision 1 as of 2011-12-19 20:13:16 →
Size: 7057
Editor: vbraun
Comment:
← Revision 44 as of 2022-03-31 02:19:04 → ⇥
Size: 0
Editor: mkoeppe
Comment: outdated
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
= The Sage Virtual Machine =

This page describes how to use the virtual machine that you can download from [[http://www.sagemath.org/download-windows.html]]. If you want to create your own virtual machine, go to the [[VirtualBox]] wiki page instead.


== Requirements ==

The Sage appliance (packaged virtual machine) can be used on any operating system that supports the free
VirtualBox 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. The virtual machine can also be used with other hypervisors like VMware. However, unless you are already familiar with VMware, we recommend that you use !VirtualBox. In our experience, it is easier for non-technical users.

== Installation ==

  1. Download VirtualBox (available at http://www.virtualbox.org/wiki/Downloads). Install it anywhere you want. Version 4 or later is required.

  1. Download the file Sage-x.y.z.ova located in the directory where this README is.

  1. Open !VirtualBox. Import `sage-x.y.z.ova` by clicking '''File''', then '''Import Appliance'''. Make sure you read the '''Information''' boxes that appear, as they explain how to type and use the mouse pointer in the running !VirtualBox window.
  
  1. If you only want to access Sage through the web browser notebook interface (i.e., to write or run worksheets), you do not need to complete any further installation. You may go on to the next section to find out how to use Sage.

  1. If you want to enable shared folders between Sage and your Windows system, complete the following steps:

   a. In the running VirtualBox window, click '''Devices''', then '''Shared Devices'''.

   a. Click on the icon with a green '''+''' in the upper right corner.

   a. Select the path of the Windows folder that you want to share.

   a. Check '''auto-mount''' and '''make permanent'''. Click '''OK''', then click '''OK''' again.

   a. From the menu, select '''Machine''', then '''Reset'''. The files will be in `/media/sf_<volume name>`.


== Using the Sage Notebook ==

  1. Start VirtualBox.

  1. To start the Sage notebook server, power on Sage-x.y.z by selecting
  it and clicking 'Start'. (This may take awhile. You may see some
  warning messages you can safely ignore.)

  1. Wait a few moments until the running VirtualBox window displays a
message saying "Open your web browser to ..." Open your web broswer
(it's best to use Firefox) to the address specified.

  1. Login with username 'admin' and the password you selected upon
installing Sage.

  1. If you would like other users to be able to create additional accounts
on the same local virtual machine, you will first need to complete some
further steps in the Sage shell (see the next section on how to use the
Sage shell).

  1. When you are finished working with Sage, logout and close your browser
as usual. In the running VirtualBox window, click 'Machine', then 'Close'.
Select 'Power off the machine' then click 'OK'. You may now close
VirtualBox.


== Using the Sage shell ==

  1. Start VirtualBox if you have not already done so.

  1. Power on Sage-x.y.z (if you have not already done so) by selecting it
  and clicking 'Start'.

  1. Once the virtual machine is powered on, press 'Ctrl C' twice to quit
  the Sage notebook.

  1. Type './sage' to start a shell interface in Sage.

  1. To work with files attached in a shared folder (if you have shared folders
  enabled), type 'attach /media/sf_<volume name>/filename'

  1. Advanced users may want to note that Sage is not
  release 4.7, so you may need to type 'su' (password: sage), or press Alt-F1
  to get a different tty and login as root, if they have trouble with file
  permissions. These are advanced options, and you should be careful when
  accessing or altering files.


== Troubleshooting ==

  * If you experience problems, get free tech support by subscribing to the
  sage-support mailing list at [[http://groups.google.com/group/sage-support]]

  * Or login to the IRC channel #sagemath on irc.freenode.net.

  * Or use http://ask.sagemath.org


== Advanced Options ==

  * You can log into the virtual machine from the text-mode console. Press Alt-F1 for a different tty. The user account running the Sage notebook server is called `sage` with password `sage`. The root account password is `sage`, too.

  * Advanced users may want to note that the `sage` user is in the sudoers file now. You can run any command with administrative rights by `sudo <command>`.



2. To allow for the creation of new users (other than 'admin') on your local
   virtual machine,

   a. Type 'cd', then hit 'Enter'

   b. Type 'nano .bash_profile'

   c. At the end of the line that begins with 'notebook', type ',accounts=True',
      then hit 'Enter'.

   d. Type 'exit'
   
   e. This enables a link on the Sage notebook login in the web browser that
      reads 'Sign up for a new Sage Notebook account'. Users can then click on
      the link and follow the instructions to create a new account.

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. Upgrading: To upgrade between stable releases, you can type "sage -upgrade"
   at the command prompt:

      [sage@localhost sage]$ sage -upgrade
      ...
      takes a while

    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.



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

Some Unix familiarity is assumed below. If you've never used anything
but Windows, some of this won't make sense.
 
  1. Change to the SAGE_ROOT directory:

     [sage@localhost directory]$ cd
     [sage@localhost ~]$ cd sage
     [sage@localhost sage]$

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

     [sage@localhost sage]$ apt-get inst
      ...

  The nano editor is included.


  1. Now type, for example,

     [sage@localhost sage]$ cd devel/sage/sage/rings/
     [sage@localhost rings]$ emacs arith.py
     [edit the file]

  or

     [sage@localhost rings]$ nano arith.py
     [edit the file]

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

     [sage@localhost rings]$ cd
     [sage@localhost ~]$ cd sage
     [sage@localhost sage]$ sage -br
     ----------------------------------------------------------
     sage: Building and installing modified SAGE library files.
     ...
     ----------------------------------------------------------------------
     | SAGE Version x.y.z, Release Date: .........