Isis for Linux

Because of the simplicity and openness of its development structure and its support for a wide variety of interface devices for audio, video, and graphics, Linux is the preferred platform for Isis. This document contains information on recommended hardware and software configurations, as well as an installation procedure using the Debian distribution of Linux.


License information

As of August 2004, it is no longer necessary to license Isis from the Media Lab in order to download and use it. Isis is available as free software under the GNU General Public License. Prior to engaging in this installation process, please read and understand the terms of this license as well as these additional disclaimers and comments:


Hardware

Below are some PC hardware specifications that we highly recommend.

  1. A standard x86-based PC with an Intel processor. Dual processor machines are even better.

  2. An NVIDIA AGP graphics card. NVIDIA cards are very well supported under Linux.

  3. A Creative Soundblaster Live/Audigy PCI sound card. Many on-board audio chipsets are not very powerful or do not support multiple sound channels.

  4. A Hauppauge WinTV video capture card, such as the WinTV Go. Other cards based on the Brooktree 878 or Conexant 2388x chipsets may also work, but we have only tried this one so far and it works just fine. USB cameras are not well supported under Linux as of yet - please do not try to use them unless you are prepared to hack with drivers.

  5. Amount of memory and disk space should be determined by what you plan to do. If you are working on an application that makes intense use of stored images or movies, we recommend getting the fastest SCSI disks available and a SCSI PCI interface card. Otherwise, an IDE disk will do just fine.

  6. A 3-button mouse. A two-button mouse with a scroll wheel that can double as the third button is also fine. We do not recommend a simple two-button mouse.


Installation procedure

Assuming you have hardware that follows the specifications described above, we have developed an installation procedure for Linux and all the software you will need to run Isis. If you strayed from the hardware specifications, or if you change any part of the procedure discussed below, you are on your own; please do not ask us for help!

This installation procedure has been updated as of August 2004. Debian is the current preferred Linux distribution for Isis. The process begins by installing the latest stable version of Debian, and then updating via the apt-get program to the "testing" version to take advantage of the latest audio and video drivers. Consequently, the machine you are installing must be connected to the Internet.

If there is a choice presented during the installation process that is not discussed in the instructions below, take whatever appears to be the default choice.

  1. Obtain CDROMs for the current stable Debian release (version 3.0). More information on where and how to obtain Debian is available on their web site. The documentation available on this site may be a helpful reference throughout the rest of the installation process.

  2. Boot the installation CDROM. If you have trouble or experience a system freeze during startup, try entering bf24 at the boot: prompt. Select your language and keyboard type as requested by the installer.

  3. If you are installing Linux on a disk that previously held another Linux or other OS installation, we recommend re-partitioning your disk by choosing "Partition a Hard Disk". If it is a new disk, you will enter this section of the installer automatically.

  4. We suggest a simple two-partition strategy: After making partition selections, make sure to select "Write" to write the partition table to the disk, and then "Quit".

  5. Follow the steps in the installer to activate the swap partition, and then the main Linux partition as the root filesystem. Make sure to choose "Ext3" as the type of the main Linux filesystem.

  6. Follow the step to install the kernel and driver modules, and then to configure the device driver modules. In this step you have to select a driver for your network interface in the "kernel/drivers/net" section, otherwise you will not be able to connect to the Internet later when you need to download updated packages. The documents that came with your computer should say what type of network interface or chipset you have. If not, you can always use a trial and error approach. "eepro100" might be a good first try.

  7. Next, you must configure the network. Enter a name for your machine, and select whether or not to automatically configure the machine via DHCP. For most, DHCP configuration will be fine. However, you may need a static Internet address for certain kinds of applications, especially those involving alot of networking or distributed processing (such as iCom or Reflexion). You can request a static address from your system administrator. You will need to get other network information from them as well: network mask, gateway address, domain name, and name server addresses. You will need all of this information during the installation process.

  8. Follow the steps to install the base system and make it bootable. Select to install LILO into the master boot record (MBR). You can make a boot floppy if you want, but it is not necessary. Then eject the CDROM and reboot.

  9. Follow the post-reboot installation steps. Select to not enable MD5 or Shadow passwords as these can interfere with NIS support. Enter a root password.

  10. For later testing purposes, we recommend creating a user account at this stage called "isis". Give it any password you want.

  11. Select "http" as the method for Apt to use to access the Debian archive and choose your region. If your first choice does not work, try another, such as the main Debian archive in the United States.

  12. Select to run 'tasksel', and select to install "desktop environment" and "C and C++". Do not run 'dselect'. Follow the instructions on the screen and choose defaults for questions that you are not sure about or don't understand. Finish the installation process and log in as root.

  13. apt-get install emacs21

  14. Edit /etc/apt/sources.list and change all occurrences of the word "stable" with "testing".

  15. apt-get update

  16. apt-get dist-upgrade

    Follow the instructions presented on the screen. You may need to re-run this step several times with a -f flag or select a non-default choice when answering a question to get everything updated without errors. (Note: you may have to choose to update a program named 'flex').

    apt-get -f dist-upgrade

  17. apt-get install module-init-tools
    apt-get install kernel-package
    apt-get install kernel-source-2.6.8
    cd /usr/src
    tar jxf kernel-source-2.6.8.tar.bz2
    apt-get install nvidia-kernel-source nvidia-kernel-common
    tar zxvf nvidia-kernel-source.tar.gz
    cd /usr/src/kernel-source-2.6.8
    apt-get install libncurses5-dev
    

  18. make menuconfig

    Here you must configure your new kernel. Follow these recommendations:

  19. make-kpkg --revision=custom.1.0 clean
    make-kpkg --revision=custom.1.0 kernel-image modules-image
    cd /usr/src
    dpkg -i kernel-image-[...].deb nvidia-kernel-[...].deb
    apt-get install nvidia-glx
    apt-get install xserver-xfree86
    
  20. Edit /etc/X11/XF86Config-4 ...

  21. update-rc.d -f gdm remove
    update-rc.d -f kdm remove
    apt-get install xscreensaver
    apt-get install alsa-utils
    apt-get install aumix
    apt-get install twm
    apt-get install vtwm
    apt-get install xterm
    apt-get install libasound2-dev
    apt-get install libglut3-dev
    apt-get install libjpeg62-dev
    apt-get install libreadline4-dev
    apt-get install libsdl1.2-dev
    
  22. Any users that will need to access the audio and video devices must be added to the 'audio' and 'video' groups. You've already created the 'isis' user, so you can add it to these groups now. If you create other users in the future, you must remember to add them as well.

    adduser isis video
    adduser isis audio
    

  23. Run the ALSA configuration program to be sure the necessary module aliases were created:

    alsaconf

  24. Create a file named /etc/modprobe.d/vidcap with the following content:

    alias char-major-89 i2c-dev
    options i2c-algo-bit bit_test=1
    alias char-major-81 videodev
    alias char-major-81-0 bttv
    

    If you have more than one capture card, add additional lines similar to the last line shown above with the device number incremented. If your card is based on Conexant 2388x instead of BrookTree, use the cx88 driver. For example, if you have a second Conexant card, add the following:

    alias char-major-81-1 cx88
    

    After making this file, run the following:

    update-modules
    apt-get install xawtv
    
    Allow the installer to create the additional devices that it wants to.

  25. Edit /etc/modules so that the sound and video card drivers will be loaded automatically at startup. (This step is necessary because there appears to be a slight weirdness with automatic loading of modules in this version of Linux). Assuming you have SoundBlaster Live/Audigy and Hauppauge WinTV cards, you will add the following lines at the bottom of the file:

    snd-emu10k1
    cx88
    bttv

  26. If your organization uses NIS (we do at Media Lab Europe and MIT Media Lab), you can install NIS using the following:

    apt-get install nis

    You will need to enter your NIS domain (get this information from your system administrator). You will also need to edit several files with information obtained from your system administrator: /etc/yp.conf (add NIS server information), /etc/hosts (add the address of your NIS server), /etc/passwd (add "+::::::" at end of file), and /etc/group (add "+:::" at end of file). You may then also want to install autofs:

    apt-get install autofs

  27. If your machine is at Media Lab Europe, make your computer aware of the internal filesystem by adding the following line at the bottom of /etc/fstab:

    homer:/u /mle/u nfs rw,nosuid,soft 0 0

    And then run the following:

    mkdir /mle
    mkdir /mle/u
    mount -a
    

  28. If your machine is at the MIT Media Lab, make your computer aware of the internal filesystem by adding the following line at the bottom of /etc/fstab:

    mas-disks:/mas /mas nfs rw,nosuid,soft 0 0

    And then run the following:

    mkdir /mas
    mount -a
    mv /etc/auto.master /etc/auto.master.old
    cp /mas/etc/auto.master.new /etc/auto.master
    /etc/init.d/autofs restart
    

  29. If you experience problems with your keyboard mapping when in a text terminal, try reconfiguring the keyboard:

    kbdconfig

  30. Reboot and choose the new kernel if it is not automatically selected. Cross your fingers and hope that it works the first time. If not, reboot into the old kernel and double check that you have successfully completed all of the steps listed above. If you see a strange error, try doing a Google search on the error message text to see if someone else has run into the problem and if there is a solution. You might also find helpful information on the Debian web site.

  31. Prior to installing Isis, you should test that all of the above software is installed and working correctly. If any of these tests fails, one of the libraries you installed previously is not working properly. You should go back and read any documentation associated with the library and get it working before you try installing Isis.

  32. To install Isis, run the following commands:

    cd
    wget http://web.media.mit.edu/~stefan/isis/downloads/install.sh
    sh install.sh
    

    Isis is installed at /usr/local/isis. This folder contains source code, libraries, executables, Isis scripts, and example programs. It is the home base of Isis on your computer. Definitions are added to the global environment so that all users of the machine will be able to use Isis.

    When installation is complete, log out and log back in and type isis. The installation was successful if you see something like this:

    *** Isis 9
    -> 
    
    Please read the README and LICENSE files installed in /usr/local/isis for information on the terms of the GNU General Public License and other important disclaimers and comments.


Problems installing

If you can't run Isis after you follow the instructions above, check the build log in /usr/local/isis/source/build.log for the word "Error". Any problems that appear are usually because one or more of the third-party software libraries needed for Isis have not been installed successfully. Check all of the documentation that came with them, and retrace your steps in the process outlined in this document. After you address any errors, you can re-build Isis by running this program:

/usr/local/isis/misc/build.sh

If you use tcsh as your shell, after installing Isis programs, be sure to type rehash to make them visible to your shell.

When you log in after installing Isis, the environment variables ISIS_SYS and ISIS_ROOT should be defined. You can test this by typing "echo $ISIS_SYS" or "echo $ISIS_ROOT".

Write to Stefan if you continue to experience problems.


Examples

As a test, you might like to try running some of the example programs in /usr/local/isis/examples, particularly the Macaroni examples. Try playing the test movie included with the distribution by entering this command in your shell:

isisu playmovie /usr/local/isis/media/repo

Remember that in order to hear any audio, you usually need to run an audio mixer program such as "alsamixer" to unmute and increase the levels of "Master" and "PCM".


Updates

To update your local Isis installation to the most recent version available, log in as root and repeat the Isis installation step described above. The installer program saves a full backup of your old Isis installation at /usr/local/oldisis, which you should remove when it is no longer needed.


Troubleshooting

Here are some common problems experienced when running Isis under Linux, and their solutions: