An Introduction to Unix for CAD users

Before You Start

This introduction assumes that you have already subscribed (registered) for access to university centrally provided computers and that you already have a user id, something like "fb2a21" (Fred Bloggs mkII January 2021) and a password. Your user id is fixed and is the first part of your e-mail address, "fb2a21@soton.ac.uk". You should be able to use the same password for all computers that you use as part of your course.

The Login Process

Log In To the Windows machine

Using your user id and password.
Start the X2go Client

The X2go Client program allows you to log in to a remote Unix machine and run programs as if you were using the machine directly.
In this lab you want to log in to a Unix machine named cadteaching7.ecs.soton.ac.uk which supports most of the CAD software that you will use.
You should be able to run the X2go Client by typing X2go into the search box in the bottom left of your Windows 10 desktop.
- This should bring up the new session dialogue into which the following data should be entered:
```
    Session preferences - New Session
      Session name:        [ CAD                           ]
      Host:                [ cadteaching7.ecs.soton.ac.uk  ]
      Session type:        [ MATE                         -]
    OK
```
  After clicking OK, you should then select the newly created CAD session which will bring up a login prompt into which to enter your user id and password.
  You can ignore warnings about authentication checks - since this is the first time you've run X2go Client it will be unable to authenticate any remote host computer.
If all goes well, you should end up with a screen looking something like the one below:

If you do not have any terminal windows visible, you should create one now using the drop down Applications menu in the top left of the screen:
```
  Applications -> Terminal
```
or
```
  Applications -> MATE Terminal
```

Command Line Unix

Although most tools that you will use are graphical in nature, they will usually be invoked through the unix command prompt (by typing) rather than through the use of icons, menus and pointers (as with Microsoft Windows). This allows for proper use and understanding of directories, an area that is very poorly supported by Microsoft's philosophy.

Move the mouse cursor over a terminal window to activate it (the border colour of a window shows whether or not it is active):

This window activation policy is called Focus Follows Mouse. The alternative Click To Type policy is also supported by the Unix machine but is less useful for the Magic layout editor that you will be using as part of your CAD work.

The following walkthrough introduces a number of key unix commands by example.

Directories

Commands to be introduced: mkdir pwd cd ls
Note that another name for a directory is a folder.
- First make a directory named design (note where <userid> is used in the text below, you should type your own user id e.g. fb2a21 in its place):
```
    cadteaching7<~>$ mkdir /home/<userid>/design
```
  Like many unix command names, mkdir is an abbreviation, in this case for make directory. You should notice that this command is silent. If it works, it doesn't print anything to the screen. This turns out to be very useful when it comes to writing scripts with unix, where 100 commands may be run in sequence but only the ones that fail will print anything to the screen.
  If you haven't got the expected cadteaching7<~>$ prompt, you should be able to get one by starting a new bash shell:
```
    bash-4.1$ bash --login
    cadteaching7<~>$
```
- Now try to make the test directory:
```
    cadteaching7<~>$ mkdir /home/<userid>/design/magic/test
```
  This command fails and prints an error message because the parent directory, /home/<userid>/design/magic, doesn't yet exist.
- The make directory command has an option that can overcome this restriction:
```
    cadteaching7<~>$ mkdir -p /home/<userid>/design/magic/test
```
  Options in unix are indicated by "-". The -p option causes all non-existent parent directories to be made.
- Up until now, absolute pathnames have been used, all starting with the unix root directory "/". The following commands make use of relative pathnames:
```
    cadteaching7<~>$ mkdir design/cadence
    cadteaching7<~>$ mkdir -p design/verilog/test
```
  Here the pathnames are relative to the current working directory.
- To find out the name of the current working directory, the print working directory command can be used:
```
    cadteaching7<~>$ pwd
```
- To change the current working the directory, the change directory command can be used:
```
    cadteaching7<~>$ cd design
```
- To list the contents of a directory, the list command can be used:
```
    cadteaching7<~/design>$ ls
```
- The list command supports a -l option to provide a long listing and -a option to view all items (including hidden items):
```
    cadteaching7<~/design>$ ls -l
    cadteaching7<~/design>$ ls -a
    cadteaching7<~/design>$ ls -a -l
```
  The hidden items "." and ".." are listed when the -a option is included.
  "." is a shorthand for the current working directory, while ".." is a shorthand for the parent directory. Thus "ls ." lists the current directory and is equivalent to "ls", while "ls .." lists the contents of the parent directory.
- For some unix commands, single character options can be combined, as illustrated by the example below:
```
    cadteaching7<~/design>$ ls -al ~/design
```
  This command also introduces another shorthand; "~" is a shorthand for your home directory.
At the end of this section you should have created the hierarchy of directories shown below. This hierarchy will be used in subsequent labs.
Files

Commands to be introduced: cp mv cat nedit lp lpr
- First copy a file into the current directory:
```
    cadteaching7<~/design>$ cp /opt/cad/bim/labs/begin/verilogfile .
```
  Remember that "." is shorthand for the current working directory.
- Then move the file to another directory:
```
    cadteaching7<~/design>$ mv verilogfile ~/design/verilog/test
```
- The concatenate command which is used to join files together, is often used simply to display the contents of a file:
```
    cadteaching7<~/design>$ cd ~/design/verilog/test
    cadteaching7<~/design/verilog/test>$ cat verilogfile
```
- Although a number of command line editors exist in unix, you will probably prefer the nedit GUI (graphical user interface) based editor when you need to edit a text file:
```
    cadteaching7<~/design/verilog/test>$ nedit verilogfile &
```
  Note the & character at the end of the command. This causes the command to run in the background so that you can continue to use the terminal window while the nedit program is running. Moving the mouse cursor between windows allows you to type in one or other window. You can change the text in the nedit window, but you should probably quit nedit without saving any changes if you want the rest of the walkthrough to work.
  A good text editor is vital for unix since the vast majority of unix files are text files - unix users like the idea that files should be readable by humans as well as by computers.
- In fact the file is a verilog hardware descrition language source file. We can run this file using the xmverilog simulator:
```
    cadteaching7<~/design/verilog/test>$ xmverilog verilogfile
```
  The xmverilog simulator looks like other unix commands, taking one or more arguments (the names of the verilog source files) preceded by options (e.g. the quiet option -q):
```
    cadteaching7<~/design/verilog/test>$ xmverilog -q verilogfile
```
- The unix filesystem does not enforce filename suffixes in the same way as Microsoft windows. Nevertheless it is conventional that a verilog file has a ".v" suffix. The move command can be used to rename the verilog source file:
```
    cadteaching7<~/design/verilog/test>$ mv verilogfile example1.v
```
- Now print the verilog file:
```
    cadteaching7<~/design/verilog/test>$ lp -d <printername> example1.v
```
  Note here that the argument for lp is example1.v while the printername is the argument for the option -d.
  In order to complete this task you need to know the name of a printer that is close to your desk.
  The printers in the Zepler computing labs and other university computer labs used for teaching can be accessed as "mono" (black and white postscript) and "colour" (colour postscript). Print jobs are initially queued and must then be explicitly released by logging into any of the printer/copier machines in these labs.
  If you have not previously printed using the university's managed print system, you will have to buy some print quota before you are able to print. You can get to the print quota page via the Applications menu in the top left of the screen:
```
  Applications -> Web Pages -> Print Quota Page
```
  While working with unix you are likely to come across an alternative print command, lpr. For this command, the option to specify a printername is "-P <printername>":
```
    lpr -P <printername> example1.v
```
  If you have problems printing directly to the printer, you may have to use the iSolutions provided print script which will prompt for a password before submitting the print job:
```
    print -d <printername> example1.v
```
- The verilog file has been copied, moved and renamed. All three operations could have been done using a single command:
```
    cp /opt/cad/bim/labs/begin/verilogfile ~/design/verilog/test/example1.v
```
- Long filenames can be awkward to type. Try typing
```
    ls ~/desi<tab>v<tab>t<tab>
```
  Where possible, the <tab> key performs "filename completion". This means that "~/desi<tab>v<tab>t<tab>" should become "~/design/verilog/test/".
Symbolic Links

Commands to be introduced: ln
With a symbolic link a file or directory may appear in more than one place in the directory hierarchy.
- If you are not currently working in your home ditectory change to it:
```
    cadteaching7<~/design/verilog/test>$ cd ~
```
- Now link the design directory with a new name "VLSI_Files":
```
    cadteaching7<~>$ ln -s design VLSI_Files
```
  Note that the -s option tells the system to create a symbolic link rather than a hard link. Hard links cannot be used for directories and will not be discussed further in this introduction.
- Finally using the following ls commands you can see the same files in more than one place:
```
    ls ~/design
    ls ~/VLSI_Files
    ls -l ~/VLSI_Files
```
Deleting unwanted files and directories

Commands to be introduced: rm rmdir
- To remove an unwanted file type
```
    rm <filename>
```
- To remove an unwanted directory type
```
    rmdir <dirname>
```
  This will only work if the directory is empty.
- To remove a directory and its contents type
```
    rm -r <dirname>
```
Use these commands with caution. There is no undo for unix rm/rmdir.

Simple Tools

In the following walkthrough, simple tools are invoked from the drop-down menus (Applications, Places, System):

or the desktop pop-up menu:

this pop-up menu is a context sensitive menu. Context sensitive menus are accessed using the right hand mouse button (also known as the MENU mouse button). The items found on the menu will depend on what is under the cursor (e.g. the desktop background pattern, the title bar of a window or a desktop icon) when the MENU button is pressed.

Open Terminal

Use the Open Terminal option on the desktop pop-up menu to open a new terminal window (remember to use the right mouse button). Note that you have already seen how to open a terminal window from the Applications menu at the beginning of this walkthrough. Having the ability to open a terminal from the desktop pop-up menu saves you having to move the mouse over to the Applications menu.
Remote Login

As an example of the use of the Applications sub-menus you should open a new terminal window for a remote computer by selecting cadteaching from the Remote Login sub-menu:
```
  Applications -> Remote Login -> cadteaching
```
A new terminal window will open and you will be requested to enter your password.
You can type the same unix commands in this new window as you have already used. Since you have a single home filestore, you will see the same files on the remote computer as you see locally (use the ls command to check that this is true).
There are a number of reasons for using this remote login facility:
- You may wish to run a complex application on a less highly loaded computer. It is simpler to do this via remote login than to log out and log back in to the other machine.
- Some applications do not run on some computers either because they have never been installed or because the version installed is incompatible with the operating system version. (The "cadteaching7" server runs the RedHat 7 Linux operating system while "cadteaching" is an older machine that runs the RedHat 6 version of Linux.)
Caja File Manager

Start the file manager from the Places menu:
```
  Places -> Home Folder
```
A file manager window should open:

Note that the window may not look identical to the picture above (The file manager provides a number of view styles which can be selected via the view menu or via the the main toolbar. The style above "Icon View" but you may find that the the file manager starts in "List View").
Using the file manager, navigate to the file ~/design/verilog/test/example1.v. You should be able to select the file and pop-up a menu with an option to Open with "Nedit" (remember to use the MENU button on the mouse for pop-up menus):

If all goes well the file will be opened in a new nedit window.
Web Browser

The ECS Web pages include course notes and lots of useful reference material. The information may be viewed using the Firefox Web browser.
The majority of your CAD laboratory notes (including this document) are published on the Web and can be found via the CAD Tools & Techniques home page:
```
  Applications -> Web Pages -> CAD Notes Page
```
After a short delay you should find yourself looking at the CAD Tools & Techniques home page, its Web address or URL is https://secure.ecs.soton.ac.uk/notes/bim/notes/cad.
Use the Web Browser to find this page; An Introduction to Unix for CAD users.
Using E-Mail

All ECS communication is via e-mail. You are expected to check your e-mail regularly in order not to miss important messages. When communicating with university staff you should use your university e-mail account rather than any other account that you have access to.
The UoS Mail option on the Web Pages sub-menu takes you to the default mail client which is the university web mail service.
Open a suitable mail client and compose a mail message to another student who is working on these exercises. Check that you can read a message sent by another student.
Remember, your e-mail address is your user id followed by "@soton.ac.uk" (e.g. fb2a21@soton.ac.uk)

Advanced Unix

Do the following walkthrough if you have time.

Sharing Files and Protecting Your Work

Commands to be introduced: chmod
When working as part of a team you may need to allow other team members to access your files. When working individually it is important to ensure that no other student may access your work. The command to use in either case is "chmod". This command modifies the rwx (read, write and execute) permissions for a file or directory.
- Create a new directory, "~/sandbox". Containing a new text file "home.html".
  Copy and paste the following text into the text file:
```
<HTML>
   <HEAD>
      <TITLE>  Page Title: My Home Page </TITLE>
   </HEAD>

   <BODY>
      <H1>     My Home Page </H1>
      <P>      Hello </P>
      <UL>
         <LI>  <A href="public/file.html"> Public </A>
         <LI>  <A href="private/file.html"> Private </A>
      </UL>
   </BODY>
</HTML>
```
  Note - when editing this file using "nedit", try selecting the Preferences -> Highlight Syntax option.
- Now create two sub-diretories "~/sandbox/public" and "~/sandbox/private" into which you should place the following files:
  - "~/sandbox/public/file.html"
```
<HTML>
   <BODY>
      <H1>     My Public Page </H1>
      <P>      Hi </P>
      <UL>
         <LI>  <A href="../home.html"> Home </A>
      </UL>
   </BODY>
</HTML>
```
  - "~/sandbox/private/file.html"
```
<HTML>
   <BODY>
      <H1>     My Private Page </H1>
      <P>      Bye </P>
      <UL>
         <LI>  <A href="../home.html"> Home </A>
      </UL>
   </BODY>
</HTML>
```
- Now use the "chmod" command to allow other users read/execute permission for all files in the "sandbox" directory (and any sub-directories):
```
    chmod -R go+rX ~/sandbox
```
  and make sure that other users can get to the directory by giving them execute permission to its parent directory:
```
    chmod go+x ~
```
- Now use the "chmod" command to deny other users read/execute permission for all files in the "private" sub-directory (and any sub-directories):
```
    chmod -R go-rx ~/sandbox/private
```
- Use the "ls -l" command to check the permissions for the files and directories that you have created.
  (Type "man ls" to find out how to decode the first 10 characters of the output from this command which has the format ".rwxrwxrwx")
- Can you read a file created by another student working on these exercises (they will also need to be using the computer named cadteaching7)?
  In the following commands, substitute <other_userid> for the user id of the other student:
```
    ls -l ~<other_userid>/sandbox
    cat ~<other_userid>/sandbox/home.html
    ls -l ~<other_userid>/private
    cat ~<other_userid>/private/file.html
```
- View your newly created HTML pages
  Although these HTML pages are not on the Web, the Firefox web browser allows you to view the pages and follow links from one page to another (unfortunately getting permission for your own university web page takes too long to be done in this session) :
```
    firefox ~/sandbox/home.html &
```
  To view somedody else's page :
```
    firefox ~<other_userid>/sandbox/home.html &
```
  What happens when you try to access these locations and follow the "Public", "Private" and "Home" links?
  Is it what you expected to happen?
- Once you have looked at the files of others (and they have looked at your files) use the following command to reduce the permissions on your home directory:
```
    chmod go-x ~
```
Note that instead of using "chmod" and direct access (as above), files may be transferred via e-mail. Unfortunately Windows mail tools such as "Outlook" have a habit of corrupting Unix CAD files! If you are working in a team, a simple and reliable way to send CAD files is via the university's SafeSend service. A better (but more complex) solution to sharing files as a team is the university's Git service.
Writing Unix Scripts

Commands to be introduced: echo sleep if-then-else-fi
script1
- Create a new directory, "~/script ". Containing a new text file "script1".
  Copy and paste the following text into the text file:
```
echo Hello World
sleep 5
echo bye
```
  This simple script contains two simple echo commands which print their arguments to the screen separated by a sleep command which yields a 5 second delay.
- Now use the "chmod" command to allow this file to be executed:
```
cadteaching7<~>$ chmod +x ~/script/script1
```
- Finally execute the new script:
```
cadteaching7<~>$ ~/script/script1
```
script2
- Create a new file, "~/script/script2 ". Containing the following text:
```
#! /bin/sh

echo Checking directory structure for user: $1

if [ -d "/home/$1/design/cadence" ]
then
  echo "Found Cadence directory"
else
  echo "No Cadence directory"
fi

if [ -d "/home/$1/design/magic/test" ]
then
  echo "Found Magic test directory"
else
  echo "No Magic test directory"
fi

if [ -d "/home/$1/design/verilog/test" ]
then
  echo "Found Verilog test directory"
else
  echo "No Verilog test directory"
fi

if [ "$2" = "autocorrect" ]
then
  echo "autocorrecting..."
  mkdir -p "/home/$1/design/cadence"
  mkdir -p "/home/$1/design/magic/test"
  mkdir -p "/home/$1/design/verilog/test"
fi

echo done
```
- Now add execute permissions for the file:
```
cadteaching7<~>$ chmod +x ~/script/script2
```
- Provided that a script or other unix command can be found in a directory within the list of directories stored in the $PATH variable you can execute the script without specifying its exact location. Type the following command to find out which directories are included in the $PATH variable:
```
cadteaching7<~>$ echo $PATH
```
This script uses the powerful if-then-else-fi construct to optionally execute one command or another dependent on certain conditions.
The script also makes use of arguments. The first argument (named $1 within the script) is the user id. The second argument ($2) is optional and supports the auto-correction function of this script.
- Delete one of the directories that you have created and then run the command with just one argument:
```
cadteaching7<~>$ rmdir ~/design/cadence
cadteaching7<~>$ script2 <userid>
```
- Run the command with two arguments and then use "ls -ld" command to check that the directory has been re-created:
```
cadteaching7<~>$ script2 <userid> autocorrect
cadteaching7<~>$ ls -ld ~/design/cadence
```
Scripts are a powerful way to save time where the same sequence of tasks is run again and again. As you become a more experienced user of unix for CAD work, you should write your own scripts as well as using scripts that are written for you.
Text Processing

Commands to be introduced: head tail wc grep sed
Unix includes a number of text processing commands that can be used directly or included in your scripts. Rather than discuss these in detail we will just show some examples here.
- Create a new directory "~/doc " and copy the file "/opt/cad/bim/labs/begin/textfile" into this directory.
- Run the following examples which demonstrate the commands individually:
```
    cadteaching7<~/doc>$ cat textfile
    cadteaching7<~/doc>$ head -5 textfile
    cadteaching7<~/doc>$ tail -5 textfile
    cadteaching7<~/doc>$ wc -l textfile
    cadteaching7<~/doc>$ grep file textfile
    cadteaching7<~/doc>$ sed -e 's/text/TEXT/g' textfile
```
- Run the following examples which demonstrate the commands working as filters:
```
    cadteaching7<~/doc>$ cat -n textfile
    cadteaching7<~/doc>$ cat -n textfile | head -20 | tail -10

    cadteaching7<~/doc>$ cat textfile | grep 'e.g.'
    cadteaching7<~/doc>$ cat textfile | grep 'e.g.' | sed -e 's/textfile/<filename>/g'
```
Command Summary

Commands used in this exercise:
- mkdir - make directories
- cd - change working directory
- ls - list contents of directory
- cat - concatenate and display files
- mv - move/rename files
- cp - copy files
- rm - remove directory entries
- rmdir - remove directories
- ln - create a link
- lp - submit print requests
- lpr - submit print requests (alternative command)
- nedit - Motif GUI style text editor
- chmod - change the permissions mode of a file
- echo - echo arguments
- sleep - suspend execution for an interval
- if-then-else-fi - construct to support conditional execution
- head - display first few lines of files
- tail - deliver the last part of a file
- wc - display a count of lines, words and characters in a file
- grep - search a file for a pattern
- sed - stream editor
Use the manual command to examine the on-line manual pages for these commands.
e.g. type "man ls" to find the manual page for the list command including the two options that you have already encountered and a host of other options that you may find useful.

Before Your Next Lab
- Finish this Lab Sheet
  
  By the time your next lab starts it is assumed that you will all be familiar with the concepts and tools described in this lab. It is expected that any lab work not completed within a scheduled lab session will be completed before the next lab session. (N.B. Since time is short for this lab it may not be possible for you to finish all the advanced unix section before the next lab - nevertheless you should ensure that this work is finished within one week of your lab session)
- Get a Log Book
  
  You will need a laboratory log book for your CAD tools & techniques work. The log book should be hard backed (not spiral bound) and A4 in size. You will need to bring your log book to every CAD lab session and you should also use it for every VLSI Systems Design assignment.
  This is where you will record your work during the laboratory sessions so that you can refer back to it later. This is where you should do all design work for your assignments. There is no need to bring any loose blank paper to the lab sessions as you will not use it - all work, however rough, is to be done in the log book.
  You should also bring Scissors and Glue to every lab session so that you can stick lab sheets and printed results into your log book.
- Ensure this Lab is Properly Documented
  
  For simple walkthrough labs such as this one, you may need to do little more than stick the lab sheet into your log book, date it and add comments and highlights where you feel it appropriate. If you have reached the end of the lab without finding anything worthy of comment, you probably haven't been following it well enough. For walkthrough labs it is not sufficient to have completed all the stages, it is also necessary to have understood what you have done, so that you can apply your knowledge in future.
Footnote - To log out select Log Out... from the System menu.

Troubleshooting (Disconnecting and Reconnecting)

If you close the X2go client without logging out, you will disconnect from the unix server without terminating your login "session". This approach is useful since it allows you to leave a program running (e.g. a long simulation) and return to it when you next connect to the unix server. On the other hand, the reconnect process does not always work (this is why we suggest logging out rather than disconnecting).
If you have left a session running and get repeated failures when trying to re-connect, you may need the help of the unix computer administrators (iSolutions) in order to solve the problem. Before contacting iSolutions, it is worth trying to make a connection using an unsupported session type (in the case of cadteaching7, the GNOME desktop can be selected). The unsupported session connection will fail but may reset the system so that you can make a new connection to the server in the usual manner.

Iain McNally

2-10-2023

An Introduction to Unix for CAD users

Before You Start

The Login Process

Log In To the Windows machine

Start the X2go Client

Command Line Unix

Directories

Files

Symbolic Links

Deleting unwanted files and directories

Simple Tools

Open Terminal

Remote Login

Caja File Manager

Web Browser

Using E-Mail

Advanced Unix

Sharing Files and Protecting Your Work

Writing Unix Scripts

script1

script2

Text Processing

Command Summary

Before Your Next Lab

Finish this Lab Sheet

Get a Log Book

Ensure this Lab is Properly Documented

Troubleshooting (Disconnecting and Reconnecting)