\documentclass[12pt]{article}

\pagestyle{empty}
\oddsidemargin 0in       %   Left margin on odd-numbered pages.
\evensidemargin 0in        %   Left margin on even-numbered pages.
\textwidth 6.5in
\textheight 9in
\topmargin 0in
\headheight 0in
\headsep 0in

\usepackage{verbatim}
\newcommand{\exx}{\\[2ex]}
\newenvironment{qv}%
  {\quote
   \verbatim}%
  {\endverbatim
   \endquote}

\usepackage[T1]{fontenc}
\usepackage{pslatex}
\renewcommand*{\familydefault}{\sfdefault}

\begin{document}
\begin{center}
\Large\bf
CS Lab Survival Guide\\
Computer Science Department\\
SUNY Potsdam\\
September 2013\\
\end{center}

\section{CS Lab}

\subsection{Location and hours}
The CS Lab is located in Dunn Hall 358.
The Lab is open during building hours,
which is generally from 7am to 11pm on weekdays
and from 8am to 11pm on weekends.

\subsection{Lab access}
The CS Lab is open to all students taking CS classes,
and all CS majors.
Your Ranger Card will allow you access to the lab
when the door is closed.
Swipe your card in the slot with the stripe facing to the right
and wait for the green light to indicate
that the door handle is operational.

If you are a CS major taking classes above CIS 300,
you also have access to the Dunn 356 High Performance Computing Lab.

You may use a CS Lab workstation even when
there is a scheduled lab session in Dunn 358 for CIS 201 or 203,
provided that there is an unusued workstation available.

\subsection{Lab deportment}
{\bf Food and/or beverages are not allowed
in the vicinity of the Lab workstations,
either on the tables or on the floor.}
Food and/or beverages are allowed on the CS Lab table near the printer.

{\bf Keep the CS Lab neat and tidy.}
Dispose of paper and other recyclables
in the blue recycling containers
and trash in the wastebasket.
The CS Lab is more welcoming to others
when it appears well cared for.

{\bf Push your chairs under the table when you are done
working at a workstation.}
There should be two chairs at each workstation location;
you are responsible for stowing both of them when you are done.

{\bf Turn out the lights and close the door when you are last to leave.}

{\bf Contact the CS Department Chair (\verb'lanzcc@potsdam.edu')
if you find anything amiss in the lab}
such as non-functioning or missing equipment
including workstations, monitors, keyboards, mice, chairs, or printers.

{\bf Disruptive or abusive behavior will not be tolerated in the lab.}
If you experience such behavior directed at you or anyone else,
contact University Police immediately (phone 2222).

\subsection{Logging in}
To log in, go to a free Lab workstation
and enter your campus computer account (CCA) username and password
in the login area of the welcome screen:
Enter your username first, followed by the \verb'Enter' key,
and then enter your password.
Your password will not display on your screen.

Your workstation username and password are the same
as your Campus Computer Account (CCA) username and password
that you can use to access other computing resources on campus.

If the screen is locked because someone else has left
without logging out,
please report this to the lab system administrator
and find another workstation to use.

\subsection{Logging out}
{\bf Be sure to log out once you are done.}
Click on the ``logout'' icon at the top of your screen.
If you do not log out,
you may prevent someone else from using the workstation later,
and you may receive an email reminding you
that you have not logged out.

{\bf Never power down any of the Lab workstations.}
Your workstation may be in use by someone who has remotely logged in,
and powering down the workstation may result
in their work being corrupted or lost.

You may leave your workstation unattended
for short periods of time,
but do not do so if you expect to be gone
for more than half an hour.

Again, {\bf push your chairs under the table when you are done
working at a workstation}.

\section{Workstation environment}

When you log in to one of the Lab workstations,
you should see a window environment
with a mostly empty screen and small panels
on the top and bottom.
On the left-hand side of the top panel
you should see an Applications menu and
icons for a terminal shell and a browser.
On the middle of the top panel
you should see a Logout icon.

You will normally begin using the workstation
by opening a terminal shell.
This gives you a {\em command line environment}
where you can enter commands
to carry out activities such as
managing your home directory;
creating, examining, and editing files;
and compiling and running your programs.
We give some example commands later in this document.

\subsection{Your home directory}
When you log in,
you will be placed in your {\em home directory},
which has the following path name:
\begin{qv}
/home/student/<your login>
\end{qv}
Here, \verb'<your login>' is your campus computer account ID,
the one that you use to log in to the workstation.
Don't confuse {\em your} home directory
with the system-wide directory named \verb'/home' --
they are not the same!

Your home directory is stored on the CS Lab server,
not on the workstation itself,
so you always have access to your same home directory
no matter what workstation you are using.

You have private access to the contents of your home directory.
You are responsible for keeping your home directory private
by not divulging your password to anyone
and by maintaining control of your workstation
when you are logged in.

In the rest of this document,
we will refer to the ficticious username \verb'user000'
and the Lab workstation named \verb'algonquin'
for the purposes of giving examples.

\subsection{Directory structure}
A {\em directory} is an area of physical storage
containing files and other directories.
On a Microsoft Windows system,
a directory is called a \verb'folder'.

When you log in to a Lab workstation,
there is a {\em top-level directory}
called the {\em root} of the directory structure.
The symbol used to refer to this top-level directory is `\verb'/'',
but we call it ``root''.

Each directory may contain files
(which can be ordinary text, executable code, or other stuff)
and other directories, called {\em subdirectories}.
It is entirely possible for a directory to be empty,
which is the case when one is initially created.

For example, the home directory of our student \verb'user000' is
\begin{qv}
/home/student/user000
\end{qv}
The directory \verb'user000' is a subdirectory of \verb'/home/student',
and the directory \verb'student' is a subdirectory of \verb'/home'.
The directory \verb'home' is a subdirectory of the root directory \verb'/'.

When you are logged in to a Lab workstation,
the symbol `\verb'~'' (called {\em tilde} or sometimes {\em wiggle})
refers to your home directory.
So if you are logged in to a Lab workstation
as a student with username \verb'user000',
the symbol \verb'~' means the same as \verb'/home/student/user000'.

\subsection{Directory navigation}

When you get a shell (see above),
you are automatically put into your home directory.
Your shell will print a {\em command prompt}
that appears like this:
\begin{qv}
user0000@algonquin:~$
\end{qv} %$
This means that user \verb'user000' is logged in
to the \verb'algonquin' Lab workstation
and is currently in the user's home directory.

You can always see what directory you are currently in
by entering the command \verb'pwd' --
which means Print Working Directory:
\begin{qv}
user000@algonquin:~$ pwd
/home/student/user000 <- this is what is printed by the pwd command
user000@algonquin:~$
\end{qv}

The directory structure forms a {\em tree},
with root at the top of the tree
(You may think that this is upside-down,
but it will appear to be OK if you are standing on your head)
and with files and subdirectories at the next level down.
The subdirectories themselves may have subdirectories,
and this progression may go on for many levels.

Your current working directory
(the one reported by the \verb'pwd' command)
is also called {\em dot} and has the (appropriate) name `\verb'.''.
The parent of your current working directory --
the directory just above it --
is called {\em dot-dot} and has the name `\verb'..''.

The \verb'cd' (change directory) command
changes to the specified directory given on the command line.
Here are some annotated examples
(given without the \verb'user000@algonquin:' part of the prompt):
\begin{qv}
~$ cd /home/student   <- change to the /home/student directory 
/home/student$ cd ..  <- change to the parent of /home/student
/home$ cd .           <- change to the current directory (no change!)
/home$ cd ~           <- change back to your home directory
~$ cd                 <- shorthand for cd ~
~$ 
\end{qv} %$

You can use the \verb'mkdir' command to create a directory
(which starts out being empty)
in the current working directory:
\begin{qv}
~$ mkdir foo
~$ cd foo
~/foo$ cd ..
~$ cd ~/foo
~/foo$ 
\end{qv} %$
Notice that the last prompt says \verb'~/foo';
this is just a shorthand for \verb'/home/student/user000/foo'.

In summary,
\begin{itemize}
\parskip 0ex
\item to move {\em up} one level in the directory structure,
  use `\verb'cd ..''
\item to move {\em down} one level in the directory structure,
  use `\verb'cd dirname''
  where \verb'dirname' is the name of a directory
  that is located in your current working directory
\item to move up two levels, use `\verb'cd ../..''
\item to move to a particular directory given its {\em relative path name}
(relative to your current working directory),
use `\verb'cd relpath'',
where \verb'relpath' does not start with a leading `\verb'/''
\item to move to a particular directory given its {\em absolute path name}
(starting at the root),
use `\verb'cd abspath'',
where \verb'abspath' starts with a leading `\verb'/''
\end{itemize}
In the above examples, the command
\begin{qv}
~$ cd /home/student
\end{qv} %$
used an absolute path name,
and
\begin{qv}
~$ cd foo
\end{qv} %$
used a relative path name.

Notice that if you start out in the directory \verb'/home/student/user000',
the following command
\begin{qv}
~$ cd ../user000
\end{qv} %$
would bring you back to your home directory again.
The name \verb'../user000' is a relative path name.

\subsection{Your directory organization}
You may want to have separate subdirectories of your home directory
for the different classes you are taking.
In each of these directories,
you may want to have subdirectories
for individual assignments
or for playing around.
To get an idea of how you might want to organize your home directory
(like organizing your {\em real} home),
take a look at the directory structure in \verb'/home/student/Classes'.

\subsection{Class-related directories}
Your instructor will let you know where specifically to find material
you will need to carry out your class-related assignments on the Lab systems.
In particular, you may be required
to copy files from a class-specific directory
into a suitable working subdirectory of your home directory.
Most class-related materials can be found
in subdirectories of \verb'/home/student/Classes'.
For example, the directory
\begin{qv}
/home/student/Classes/201
\end{qv}
will contain materials specific to CIS 201.
Carefully follow the instructions in your assignment
to be sure that you have all the files in your working directory necessary
to carry out the assignment.

\subsection{Your Desktop}
The ``desktop'' that appears on your screen when you log in
shows the contents of a directory named \verb'Desktop'
in your home directory.
You can change to this directory in a command shell
using the following:
\begin{qv}
cd ~/Desktop
\end{qv}
Everything in this directory will appear
as an icon on your desktop screen.
Adding, renaming, or deleting files in this directory
will result in those changes appearing on your desktop.

You can open a file manager application
that will display the contents of other directories
in a file manager window.
From this window you can ``drag and drop'' files
between the file manager window and your desktop,
or even between two file manager windows.
Other operations such as ``copy and paste'' or ``delete''
are possible on your desktop or in a file manager window.
All of these sorts of operations can be done
using commands from a shell window,
which is what most Linux programmers do.

\section{Useful commands}
\begin{quote}
\begin{tabular}{lll}
{\bf command} & {\bf example} & {\bf description} \\
\verb'pwd' & \verb'pwd' & display the current working directory \\
\verb'cd' & \verb'cd /home' & change directory to \verb'/home' \\
\verb'rm' & \verb'rm bar' & remove the file \verb'bar' \\
\verb'rmdir' & \verb'rmdir foo' & remove the directory \verb'foo' \\
  & & the directory must be empty for this to work \\
\verb'mv' & \verb'mv bar car' & rename the file \verb'bar' to \verb'car' \\
\verb'mv' & \verb'mv bar foo' & move the file \verb'bar' into directory \verb'foo' \\
  & & \verb'foo' is assumed to be a directory in the above \\
\verb'cp' & \verb'cp bar far' & copy the file \verb'bar' onto the file \verb'far' \\
          & \verb'cp ../bar .' & copy the file \verb'../bar' to a file \\
  & & of the same name in the current directory \\
\verb'cat' & \verb'cat bar' & display the contents of the file \verb'bar' \\
\verb'ls'  & \verb'ls foo'  & list the contents of directory \verb'foo' \\
           & \verb'ls -l foo' & do a long list (with details) of \verb'foo' \\
           & \verb'ls'      & list the contents of the current directory \\
\verb'lpr' & \verb'lpr bar' & print the file \verb'bar' on the Lab printer\\
\verb'javac' & \verb'javac Prog.java' & compile \verb'Prog.java' \\
\verb'java' & \verb'java Prog' & run the \verb'Prog.class' program \\
\end{tabular}
\end{quote}

\subsection{Wildcards}
When a command requires one or more filename arguments
(such as \verb'javac'),
you can use wildcards to refer
to all of the filenames that match a particular pattern.
The most common wildcard is `\verb'*''
which matches any (zero or more) filename characters.
For example, the following command
\begin{qv}
javac *.java
\end{qv}
will compile all of the Java files in the current directory.

\subsection{Man pages}
Most commands have on-line documentation that you can read
to find out the various {\em switches} (options)
that are allowed for the command.
The \verb'man' (for {\em manual}) program
will display this on-line command documentation,
as the following example shows:
\begin{qv}
man cat
\end{qv}

\subsection{PATH}
Your \verb'PATH' is a colon-separated list
of directories that the shell uses
to determine the location of a command that you enter.
You can see your \verb'PATH' by using the following command:
\begin{qv}
echo $PATH
\end{qv} %$
If you want to run a program that is not in your \verb'PATH',
you can do so by naming the program with an absolute or relative path name.
For example, if you compile a program \verb'hello.c'
using the \verb'gcc' compiler,
the compiler will produce an executable named \verb'a.out'
in your current directory.
But your current directory is almost certainly not in your \verb'PATH',
so to execute this program you would need to do
\begin{qv}
./a.out
\end{qv}
where the `\verb'./'' part (pronounced ``dot-slash'') says
to look in your current directory
for the program to run instead of looking
in the directories in your \verb'PATH'.

\section{Redirection}

Many programs take input from {\em standard input}
and send their output to {\em standard output}.
Unless directed otherwise,
standard input comes from your keyboard,
and standard output goes to your shell window.
In Java programs, \verb'System.in' refers to standard input
and \verb'System.out' refers to standard output.

Programs may also send their output to {\em standard error},
which also defaults to your shell window
but is used principally to report error messages.
In Java programs, \verb'System.err' refers to standard error.

When running a program that writes to standard output,
you can {\em redirect} the output to go to a file instead
using the `\verb'>'' redirection operator:
For example, the following command
\begin{qv}
ls > DIR
\end{qv} 
would send the output of the \verb'ls' command
to the file \verb'DIR' instead of sending it
to your shell window.
Similarly, if \verb'Prog' is a Java program
that reads from \verb'System.in',
the following command
\begin{qv}
java Prog < DIR
\end{qv}
would read its input from the file \verb'DIR'
instead of from the keyboard.

\section{Pipes}
A {\em pipeline} is a concatenation of commands
where the output of one command becomes the input to the next command.
In this case we say that the one command {\em pipes} its output
to the next command.
The vertical bar operator `\verb'|'' is used
to denote a pipe.
In the following example
\begin{qv}
ls | java Prog
\end{qv}
the output of the \verb'ls' command
becomes the input to the Java program \verb'Prog'.
Notice that this amounts to the same as the two commands
\begin{qv}
ls > DIR
java Prog < DIR
\end{qv}
without the need for the intermediate file \verb'DIR'.

\section{Remote login}
You can log in to the CS Lab from off campus
using a {\em remote shell}.
On a Microsoft Windows system,
you can install and use \verb'putty'.
However, logging in remotely from a Windows system
will generally not allow you
to execute programs on the Lab systems that are graphics-oriented,
such as \verb'gedit' or \verb'emacs'.

On a Linux system such as Ubuntu,
you can use \verb'ssh' to log in remotely.
Doing so will give you a command shell
that is the same as if you were running the shell
on the lab system.
If you give the `\verb'-X'' command-line switch to the \verb'ssh' command,
this will route graphics-oriented output
from the Lab system to your remote system.
If you do not have a Linux-based system,
you can install \verb'virtualbox'
to set up a Linux virtual machine
that will behave appropriately.

To use \verb'ssh' from a remote Linux system,
run the following command:
\begin{qv}
ssh -X user000@lab.cs.potsdam.edu
\end{qv}
where you should replace the \verb'user000'
with your username.
You will be asked to enter your CCA password,
after which you will get a shell
on one of the Lab workstations that you can use
as if you were sitting at the Lab workstation.

If you want simply to copy a file
between a remote Linux system and the Lab server,
you can use the \verb'scp' (for ``secure copy'') command.
Here's an example of how to use \verb'scp'
from your remote Linux system:
\begin{qv}
scp user000@lab.cs.potsdam.edu:foo .
\end{qv}
This will copy the file named \verb'foo' from your Lab home directory
into the file with the same name on your remote Linux system.
You can also copy in the other direction,
from your remote Linux system to your Lab home directory;
see the \verb'scp' documentation for details.

{\em If you do your work in the Lab instead of remotely,
you have the advantage of being able
to discuss your homework with your peers and faculty who are on campus,
and you will also get to know your fellow students better.}
One of the best ways to become a successful CS student
is to become a part of our CS family
by working and playing in our CS Lab environment.
We recommend that you use remote login rarely.

\section{USB drives}
You should be able to plug a USB device into
one of the USB slots in the front of a Lab workstation
to access the files in the device.
You will typically get a file manager window showing
the contents of your device,
and you should be able to copy files and directories
between the file manager window and your desktop
by using conventional drag-and-drop or copy-and-paste operations
that are familiar to Windows users.

The directory structure of each USB device that you plug in
will appear as a subdirectory of the \verb'/media' directory,
with a name that comes from the device ``disk label''.
You might see, for example, a directory named
\begin{qv}
/media/XXX
\end{qv}
if the USB you plug in has \verb'XXX' as its disk label.
You can cd to such a directory
to perform operations on the device
as you would any other directory.
If you leave your file manager window open during the use of the device,
you can ``Eject'' the device
from this file manager window,
which will commit any changes to the device that are pending.
Unplugging a USB device without ejecting it
can result in device corruption, although this is rare
if you have not been accessing the device for a few minutes.

A particular USB device may have a filesystem that is formatted
in such a way that a Lab system doesn't understand its organization.
In this case, the Lab system may not be able to give you access
to the content of the device.
If this happens, and if you need to access the contents of the device,
you may get help from the system administrator.



\section{Editors}
To modify a file such as a Java source file,
a document, or a test file,
you need to use an {\em editor}.
An editor is a program that allows you
to make changes to a file.

Everyone has their favorite editor,
and we will not play favorites here.
However, one of the following editors
(listed in alphabetical order)
should serve you well:
\begin{quote}
\verb'emacs' (pronounced ``ee-macks'')\\
\verb'gedit' (pronounced ``gee-edit'')\\
\verb'jedit' (pronounced ``jay-edit'')\\
\verb'nano'\\
\verb'vi' (pronounced ``vee-eye'')\\
\end{quote}

\section{Miscellany}
The names of the CS Lab systems come
from the Adirondack High Peaks.
Mount Marcy, the tallest,
has an elevation of 5,343 feet.
The artwork on the walls of the Lab
are on loan from the Gibson Art Gallery
and are intended to be suggestive
of the Adirondack mountain region.

The CS Lab workstations and server were replaced in Summer 2013.
Each workstation is a Hewlett-Packard Z620
with a Xeon processor (3+GHz), 12Gb memory,
500 GB disk space,
and an Nvidia GTX480 GPU graphics card.
The Lab server is a Hewlett-Packard rack server
with 1.5TB storage, dual Xeon processors, and 32Gb memory.

Home directories on the Lab server are scheduled daily for backup,
at two separate locations, in the wee hours of the morning.
If you have files or directories that you have mistakenly
overwritten or deleted,
you can request that the system administrator restore
your backed up versions.
Any changes that you made after the backup will be lost.
Even though backups are scheduled daily,
their successes are dependent on factors such as
network connectivity, power availability, and hardware reliability;
{\em the system administrator cannot guarantee
that files will be restored to their prior contents.}

\section{This Document}

The \LaTeX source file for this document is named \verb'survival.tex'
and is located in the directory
\begin{qv}
/home/student/Classes/Survival
\end{qv}
on the CS lab server \verb'cs.potsdam.edu'.
The PDF version of this document is
\begin{qv}
/home/student/Classes/Survival/survival.pdf
\end{qv}

\end{document}
