/users/rlr/Courses/intro-Unix.txt
http://cscs.umich.edu/~rlr/531-09F-Src/intro-Unix.txt

A Very Short Introduction to Unix, emacs and compiling/running a simple program.
--------------------------------------------------------------------------------

For an introduction to using the CSCS computers, please be sure
 to first read:

   http://www.cscs.umich.edu/PmWiki/pmwiki.php?n=Site.Documentation

That includes basic information on:
 - the computers in the CSCS lab
 - logging in from remote machines
 - changing your passwd
 - Your login shell
 - file backups
 - large volume scratch space for users
 - checking your e-mail on CSCS machines
You should scan those pages, so you know roughly what is there
and can go back to find things as needed.
You also should bookmark that page.

You can find a couple of useful linux/unix tutorials &etc off this page:

   http://www.cscs.umich.edu/PmWiki/pmwiki.php/Site/ProgrammingLinks

**** IMPORTANT NOTE ****

==> When you are done using a CSCS machine, remember to logoff!!  
    To do that from a Linux console in the Lab:
      Click on System in the menu bar and select the log out option.  
      Then **BE SURE TO** select Yes to to confirm logout.
    On any machine, be sure the Login Screen comes back up
    before you leave...then you can be sure you have logged off.

*** NEVER NEVER NEVER TURN THE COMPUTERS OFF ***

Thus the rest of this introduction assumes you are logged into
a CSCS linux machine, either directly or via ssh from another computer
(in the lab or from outside the lab).

=======================================================================
General Note:   Don't worry, be Happy!
--------------------------------------
Its *very* hard for you to "crash" a unix workstation.
If your program "crashes", usually it will just stop.

One other "bad thing" your program might do is go into
an infinite loop.    If it does, you can either 

a) press Control-C to stop it (if its not "in the background")

b) use the linux "kill" command to stop it. 
   Each process (eg run of a program) has a unique integer ID
   assigned to it.   You can find out what jobs you have running
   by entering (in another window, eg):

      ps aux | grep yourLogin

   (substituting your login for "yourLogin").
   You will see a series of lines, one for each "process".
   The second column from the left is the process number
   and the far right of the line has the command used to start the process.
   So assume the process you want to stop is 12345.
   To stop that job, enter:
      kill 12345
   or if that doesn't do it:
      kill -9 12345


-----------------
Login in and out.
-----------------
From other unix machines, or machines with a ssh client:

  ssh yourLogin@lastrada.cscs.lsa.umich.edu

Note that you CANNOT backspace to make corrections in your
login or password.  You will have to do it right or start over.

To logout from a remote connection, type 
   exit

** NOTE **
You must use ssh (SecureShell) to make connections to CSCS machines.
You can get this free program on any computer; its already on
most linux/unix computers.   For information on how to get it, see:

   http://www.cscs.umich.edu/PmWiki/pmwiki.php?n=Site.LabSecurity

From Windows machines, you must use putty to login and Hummingbird Exceed
to make it possible to display "GUI"s remotely.  See this page
for how to do that:

   http://www.cscs.umich.edu/PmWiki/pmwiki.php?n=Site.UsingHummingbirdExceed

Once you are logged into a CSCS machine in the CSCS Lab, one way to get
"terminal" windows (windows into which you can type commands) is to:
   - move the mouse into the background area on the screen
   - hold down MB3 (usually the right button)
   - select "Open Terminal"

Note you have 3-button mice.  The function of the various
buttons depends on the program the poke is directed towards.
In general, the left mouse button (MB1) is the "basic"
button for poking icons, menus, etc.
You can stretch a window by grabbing (MB1) at the edges and corners;
You can move windows by placing the mouse in the window title bar,
holding MB1 (left) and dragging (or try pressing ALT-mb1 anywhere
in the window and dragging).

Note that its useful to have several "terminals" open to the same machine, 
e.g., so you can run a program in one window, and use "top" or other 
commands to monitor the program's execution in another.

*** NB ****
***     Case matters for commands:
***        Example:    ls report   is not the same as:  ls Report
***     Sometimes space matters, sometimes not.
***        Example:     ls-l   is not equal to:    ls -l
***
*** Also note that el 'l' and one '1' sometimes look similar in
*** hardcopy printouts.  In the examples above, those are all "el"s.
*** Also note zero (0) vs capital "Oh" character (O).
*** So if you try an example with one of those and it doesn't work,
*** try it with the other!


Directories
-----------
Linux/unix uses a tree/hierarchy/folder structure,
just as you find under Windows or the MacOS.
A directory is the same as a folder.   But Case Matters!  
The front-slash ("/") separates directory names in
linux/unix (as does the backslash in Windows).

Each user has his/her own home directory (folder),
within which all of his/her subdirectories and files
will be stored.  Your home directory will be something like:
     /users/yourLogin
where yourLogin is your uniqname/login name.
This:

  ~joe 

is short for "the home directory of the person with login joe".
So for example, 

   ls -la ~joe

will list all the files in joe's home directory (note the el's!)

In each xterm window, you are entering commands to a
"command shell" which processes those inputs and decides what
program to run, command to execute, etc.
In each xterm window you are "in" a "working directory".
To see where you are, use the print working directory command:

  pwd

To see what is in the current working directory, use the list command:

   ls -l -a

where the -l (el) and -a are parameters controlling
the behavior of the ls command:
    -l   list in long format
    -a   list all files (including dot-starting files)

Another way to see what is in your current working directory: 
    ls -l -a .    
The . (dot) is optional, and just means "in the current working directory".
To see what is in the directory "above" (containing) the
current working directory:

  ls -l ..

The .. (dot dot) means "in the directory above the current directory"
i.e., the directory in which the current working directory is located.

When you enter commands that require an input or output file or
directory, if you don't specify one, the commands will often
just assume you mean the current working directory.
Also, you can refer to files in other directories by specifying
their location relative to the current working directory.
Thus the example above

   ls -l -a ..

refers to the directory above the current working directory, and

   ls -l -a ../someOtherDirectory

refers to a directory called "someOtherDirectory" which
is located in the same directory (folder) as the current working
directory.

You can also refer to files and directories by specifying
"absolute paths"...see the tutorials referenced above for
more details on directories, relative paths, absolute paths,
and related topics.

When you do  "ls -la" in your home directory, you will see a
lot of files that begin with . (dot). 
Those dot-files in your home directory contain information
to automatically configure various programs when you start them, e.g.:
   .login  --- commands done when you login
   .emacs  --- startup commands for emacs
In general, you won't need to change/look at these until you
are a more advanced unix user. 

**** NOTE WELL: There is NO TrashCan from which removed files can be
****            recovered.  When its gone, its gone!!
****      Well, that's not exactly true--there are backups made
****      at certain times of the day and week.  Please read
**** http://www.cscs.umich.edu/PmWiki/pmwiki.php?n=Site.GettingStartedBackups

Make and remove a directory:
  mkdir TwoPlusTwo
  rmdir TwoPlusTwo

Make it again, go there, see there is nothing there:
   mkdir TwoPlusTwo
   cd TwoPlusTwo
   ls -la

To go back "up" to your working directory:
   cd ..             (.. always refers to directory "above" where you are)
   pwd               to see where you are
   ls                to see what is there
   ls TwoPlusTwo     to see what is in TwoPlusTwo/

And then back down to the TwoPlusTwo
   cd TwoPlusTwo
   ls -l ..             to see what is in the directory above where you are
   ls -l                to see what is in directory where you are now (TwoPlusTwo)
   ls -l ../TwoPlusTwo  hard way to see what is in TwoPlusTwo !


Running programs in the background
----------------------------------
As mentioned above, you run programs by typing commands in at the shell prompt.
The prompt normally will not re-appear until the program is done.
In some cases that is not convenient, e.g., when you start up a broswer
that you want to keep using for an entire session.
In those cases, you should append the amphersand (&) character to the
end of your command to tell linux to run it "in the background" as in:

  firefox &

to start the firefox (mozilla) broswer.  Another common use is when running
emacs to edit files (see below), or running any other GUI-controlled programs
(e.g., RePast programs).


---------------------------------------------------------------------------

Creating a simple Java program
---------------------------
Basically a Java (or C or C++ or ...) program is created as follows:
 - use an editor to type in the "source" form
   of the program, i.e., the program written
   in the human-readable Java language.
 - use a compiler to compile the Java program files
   into "object" (sort-of) files.   These are files in
   a machine readable format, which contain the
   various parts of the program, but not ready to run.
 - Ask the Java program to run your program!

[For some languages, e.g., C, there is another step:
use a linker to combine the object files, along with standard C 
library files, to create an "executable" (i.e., run-able) program.]

In this example, you will first just copy the Java source
code files into a directory in your file space, to save you having 
to type it in.  You will then compile it, so you have a 
program you can run in your own directory.
And you will have the source for that program, so you
can change the program, re-compile it, and thus
get it to do different things when run.

So, to start, if you haven't done so (see above),
create a directory TwoPlusTwo and "cd" into it:
   cd TwoPlusTwo
Then copy (cp) the provided source files in to your directory:

    cp /users/rlr/Courses/531/Src/TwoPlusTwo/*.java  .

** Note the "." dot character at the end of that line!!
That command says "copy all the files that end in "java" from the 
named directory into the current working directory."
Command recall editing can save a lot of keystrokes, especially
if you are a sloppy typist (like me!).  
See what is in the TwoPlusTwo directory now:

   ls -l                   (that is: el es space dash el)

To see what is in an (ascii text) file:

   cat Readme.txt

See the "less" command for a better way to do this.
Or use emacs to edit the file to see what's in it.

Next compile the program:

    javac TwoPlusTwo.java

After it is compiled, to run your program:

    java TwoPlusTwo

You should see some simple output printed in your terminal window.  

You can now look in the source files to see what the 
program looks like, using any editor you want.
However, to edit files in Linux/Unix, I recommand emacs:

   emacs TwoPlusTwo.java & 

There is a tutorial in Emacs (from a pull down menu),
or get an introduction to Emacs book.
(Or see the MediaUnion notes mentioned above...)
To edit two files at once, you can use the File->OpenFile menu
item, or you can press F7 (top of keyboard on the computers in the lab).
In either case, you will be prompted for a filename to open.
Eg, try to open the Readme.txt file in a second window.
To flip back and forth between the files, you can use the
Buffers menu item, or you can press (at same time) 
   <Cntrl>-Mouse1 (usually left button)
A list of open files will appear: slide pointer to the one
you want and release.

There are also some special functions defined for some of the
"Function" keys on the keyboard.  These are defined in your
.emacs file (see above) on the CSCS computers.
A couple of other useful keys:
   F1 - open new file in new window
   F2 - open buffer in new window
   F7 - open new file in current buffer
Again, see various emacs docs for zillions of other commands and shortcuts.

Next, make a copy of that TwoPlusTwo.java file:

   cp TwoPlusTwo.java  TwoPlusTwo-original.java

Now make a change to the file (TwoPlusTwo.java) you are editing.
For example, change a line like this:

		double db = 4;

to this:

        doulbe db = 4;   // oops, 

Save the file, via the menu File->Save, or ^X^S
Then compile the program again:

    javac TwoPlusTwo.java

You will see some errors.
The diff program can remind you what you changed:

   diff TwoPlusTwo.java  TwoPlusTwo-original.java

Change that line back in the emacs window, recompile.
You will still see the errors! Why?  
Save it, recompile, and it should be aok.

To leave emacs, File->ExitEmacs or Ctrl-X Ctrl-C (^X^C) 

----------------------------------------------------------------------
I (rlr) don't recommend it, but Josh does:

A simple editor to try  is the text editor "gedit", which is
accessible via "RedHat Menu -> Accessories" -> "Text Editor" .
It has anti-aliased fonts, and other nice features.
But it does NOT have syntax color highlighting, or the ability
to make and debug programs within the editor (as you can in emacs).

Other popular editors are pico and nano !

----------------------------------------------------------------
To rename files, use the mv (move) command:
   touch xxx       <- this just creates an empty file named "xxx"
   ls -l
   mv xxx yyy
   ls -l 

To remove files, enter "rm filename"
   rm yyy

To remove a directory and all the files in
directories in it:
   rm -r someDirectoryName

BUT BE CAREFUL:  as noted above---there is no trashcan!! 
It takes extra work to recover files, and that can
only be done if the file is saved to our weekly filesave tapes.

----------------------------------------------------------------
The "man" command can give you details about any command:
   man ps
   man ls
   man less            "less" is a good way to read text files
   man who             
   man top
   man grep

See who else is logged it:      who
How busy is the machine:        top    (Control-C to quit top)
How busy are all the machines:  qhost
  (rough estimates...)

----------------------------------------------------------------
Sometimes its useful to see what command is being executed
when you type in a command/program, e.g., when there are multiple
versions with the same name, in different directories in your PATH
(the list of directories unix looks through to find commands you enter).
   which javac
will show you which javac compiler you are using by default.
Sometimes when you run a command (or a program of your own)
and it doesn't do what you expect, it can be because its really
running some other version!

----------------------------------------------------------------
grep (general regular expression parser, I think) is very useful
for searching files for strings.  For example, suppose you want
to find all occurences of some variable name in your
*.java files:
    grep  -n double *.java
The -n tells it to print the filename and line number along with
each line that has "double" in it.
You can search for various "regular expression" patterns:
    grep -n "do*"  *.java
will find "double", "dose" and so on.

----------------------------------------------------------------
In unix there is a concept called a "pipe", for piping data
from the output of one program directly into the input of another.
An example of this was shown above:
   ps aux | grep yourLogin
(Again, subsitute your login for "yourLogin".)
The veritcal-bar character (|) is the pipe from the "ps -ef"
command to the "grep yourLogin" command.
To see the output of the ps command, just enter
   ps aux
All that output goes into the "grep" command, which in
effect acts like a filter, printing out only those input lines
that have the string "yourLogin" in them.
Many unix commands are written so they can be strung together
in pipelines.  See any introduction to unix for examples.

----------------------------------------------------------------
We have two postscript printers in the CSCS lab, but by
default all printing is done on the duplex (two-sided)
black-and-white printer called "calamaro".  To print postscript files:
   lpr -Pcalamaro alife.ps
This printer is located in the CSCS Commons room, next to the lab.

To list program files, or other plain text, I find 
   enscript -2rG -T4 -Pcalamaro  TwoPlusTwo.java
useful, as it puts info at the top, and prints two-pages side
by side, indents Tab's 4 spaces  (and so saves a few trees).
Enter "man enscript" for more information about its parameters.

** IMPORTANT **
Remember, if you login from some remote site, and you enter
a print command (lpr or enscript or whatever) in a session
running on a CSCS computer, it will print the the CSCS lab,
*NOT* on the printer at your remote site!!
You have to transfer the file from the CSCS computer to
the local computer to print on that local printer.

----------------------------------------------------------------
To copy an entire directory:
   cd          (cd to your home dir)
   cp -r TwoPlusTwo TwoPlusTwo-x
   ls -l
To rename a directory
   mv TwoPlusTwo-x TwoPlusTwo-y
   ls -l
To remove it (***be careful***)
   rm -r TwoPlusTwo-y

------------------------------------------------------------------

**** IMPORTANT NOTE ****

When you are done at the CSCS machine,  remember to logoff!!  

***\                                  /***
**** BUT DO NOT TURN THE COMPUTER OFF ****
***/                                  \***
----------------------------------------------------------------------