#------------------------------------
#--  Lec-1-HW-2-tutorial
#------------------------------------

NB--Read this entire document BEFORE doing anything.
NB--In what follows, we will use Makefile syntax:

URL1=https://svn.cs.georgetown.edu/svn/projects
URL2=https://svn.cs.georgetown.edu/svn/projects2/120-2013
AUTH=--username 250-374-developer --password 'y(&qwqsq'

By macro substitution, this,

        ${URL2}/CourseDocuments

becomes this,

    https://svn.cs.georgetown.edu/svn/projects2/120-2013/CourseDocuments

If you put the above definitions in a file "Makefile", you can use 
"make" to execute long commands that would otherwise be prone to 
typing mistakes. For instance, if this is in your "Makefile",

x::
	svn log -v ${URL2}/CourseDocuments ${AUTH}

(NB--There is a tab character before "svn". That is critical.)
You can do this to see the log of changes to CourseDocuments,

%> make x

==============================
= Setting up, overview
==============================

URL1 is the address of our svn repository that holds project 
materials you will be using. These include some tools and 
documentation.

If you checked out URL1, you can use your operating system's copy 
command (e.g., "cp" in unix) to get copies of files and move them to 
your working copy of your branch, and then perhaps "svn add" them to 
your branch. 

We will be working from your unix home directory. You get there by 
opening a terminal window (or cygwin window) and typing,

    cd

-------------------------
Note on Windows file systems

For Windows systems, cygwin and Windows do not agree on the shape of 
the directory tree of the entire file system. For Windows, the actual
root is "C:\", e.g., if you are using your C: drive. Cygwin is usually
installed in C:\cygwin\ with your unix home below there. To get to
the Windows root, C:\, using cygwin, do this,

    cd /cygdrive/c/

Note that you have two home directories: (1) your cygwin home which
is in cygwin's /home/, and your Windows home, which is probably in,

    /cygdrive/c/Users/

It can get confusing. It is best to keep your work in your
unix home directory which is under /home.
---------------------------

---------------------------
Note on documentation

You will find information on the various files and tools needed 
for our LC3 project in,

    ${URL1}/LC3-trunk/docs/ 

Peruse the READMEs and other files to get an idea of what's there.
Also take a look at the verilog documentation in "docs/verilog/".
Also note that each directory in LC3-trunk has READMEs and
Makefiles which contain information and instructions.

If you are unfamiliar with unix, read, e.g., docs/README-unix.
If you are unfamiliar with a command line editor (vi or emacs),
read the relavent READMEs.
---------------------------

====================================
== Checking out your working copy
====================================

Your own branch has been created for you in,

    URL2/branches/

Check out a working copy of your branch on whatever machine you
are going to use, "cd" to where you want to put your working copy,
and "svn co". For example,

    svn co ${URL2}/branches/Squier ${AUTH}

substituting "Squier" for your last name. 
Your local copy is called a "working copy" of your branch. 

You can have multiple working copies on the same or different 
machines simultaneously. You can delete a working copy at any time 
this way,

    /bin/rm -rf Squier

But, if you had changes that were not checked in to your branch,
they will be gone. If your working copy is corrupted and you cannot
checkin, move your changed documents to a temporary, safe place,
then /bin/rm your working copy. Check it out again, and copy your
work into the new working copy. 

Check in your work frequently. But first check that your working
copy is up to date, and check what will happen when you do "svn ci":

    cd Squier
    svn up
    svn status

Then do the check in:

    svn ci

MAKE GOOD COMMENTS when you "svn ci",
ALWAYS PRECEDED WITH YOUR INITIALS.

WHY? Helps you know what you did; Helps me know who you are 
and what you did: I may have to undo your mistakes.

To see those commit comments,

    svn log -v ${URL2}/branches/Squier ${AUTH}

-------------------------------------
svn ci and the unix environment variable "VISUAL"

"svn ci" starts an editor for the commit message. You need to have 
an editor specified via your VISUAL environment variable. svn will
read this variable to start the editor. If you do not have VISUAL
set, svn will choke, saying "no editor specified".

The bash shell reads ".bash_profile", which is in your unix home 
directory (aka, "~"). Set VISUAL there (I use "vi"):

    cd
    vi .bash_profile

At the bottom of that file, add this line,

    export VISUAL=vi  

Then do this in your unix shell,

    cd
    source .bash_profile
    echo $VISUAL

If all went well, you will see "vi" displayed as
the value of your environment variable VISUAL. 
(To see the values of all your shell variables, do "set".)
-------------------------------------

========================
= Checking out a copy of /projects
========================

In the same way we did above, you can check out a copy this way,

    svn co ${URL1} ${AUTH}

DO NOT "svn ci" or "svn import" in your copy of projects/.
ONLY DO "svn up", which will get any modifications I may have made
to its contents. (Aside, NEVER DO "svn import" anywhere!)

===============================
== Doing the Electric tutorial
===============================

Find your copy of the tutorial,

    Squier/lib/tutorial.jelib

Get a copy of Electric from here:

    ${URL1}/LC3-tools/

Try running it: double-click it, or,

    java -jar electricBinary.jar

in a unix terminal window.

If your system does not have Java installed, google "Java" and 
go to Sun's web site to download and install Java. 

Open your lib/tutorial.jelib in Electric using, 

    Electric.File.OpenLibrary

It may take some navigating to find your lib/ (scroll up to see 
parent directories). Work your way through the tutorial just until 
you feel you have the hang of using Electric (see the README cell in 
tutorial.jelib). 


=======================
= Using verilog
=======================

Create a verilog file from your design, 

    Electric.Tools.Simulation(Verilog).WriteVerilogDeck

We want to run iverilog, but we need to update your environment 
variables, particularly your PATH variable which locates executables. 
First, we need to find the path to your iverilog executable. For instance, 
iverilog might be here,

    /cygdrive/c/iverilog/bin/

if you took all defaults when installing iverilog on a Windows 
machine. On a unix machine, depending on how you installed it, 
it is someplace. In either case, the installation script might 
have already set up your PATH. Try this,

    which iverilog

If the shell can find iverilog, it will show you the path to it.
In that case, you are done because your PATH is already setup.
If not, here's one way you can find it,

    find . -name "*iverilog*"

The pattern "*iverilog*" matches any string in the file system
with "iverilog" embedded in it; e.g., "iverilog.exe" on Windows.
The "." means start searching from the current directory; so, you
should cd to someplace up in the file system tree to start searching.
Because "find" will search everywhere below where it is started, this 
could take quite a while if you start at "/" or "/cygdrive/c/",
for instance. Wherever iverilog is, we will want our PATH environment
variable to include that path.  In your unix home directory, open 
".bash_profile" in an editor. Here is an example of what you might add,

    PATH="/cygdrive/c/iverilog/bin:${PATH}"

as the last line in that file. That is a shell command, and it
is read by the first bash shell created when you logged in
(i.e., opened a terminal window). After having done that, if 
you exit your shell and log in again, your PATH variable will have 
the path to the iverilog executable pre-pended. You can check 
this with,

    echo $PATH

Setting your PATH will allow you to type,

    iverilog

whenever you want to run it, wherever you are currently in the file
system tree. Otherwise, you would have to type the entire path, e.g.,

    /cygdrive/c/iverilog/bin/iverilog

to invoke iverilog. This part of the assignment is to get your
PATH variable set so that iverilog works, and so that any executables
you put into bin/ (or wherever) will also work. This is needed so
that Makefiles work correctly in src2/ and elsewhere.

------------------------------------
Note on local executables

If an executable is in your current directory, you can use,

    ./foobar

where "foobar" is the name of the executable, without setting your PATH.
You can add additional lines to your .bash_profile as was done above 
to add paths to other executables into your PATH variable.
-------------------------------------

=====================================================
== WHAT TO TURN IN 
=====================================================

Turn in a coversheet and comments on all steps you attemped.
Tell how things worked or didn't. Describe problems that
resulted with some detail. And, if your description is detailed
enough, we might be able to understand and help you with it.
Also, commit any work to your branch, such as documents you
have created, test files, scripts, libraries, and program
code.


====================================
== NOTES ==============================
====================================

------------------------------
Some Electric shortcuts
------------------------------
NB--In what follows, "C" means hold down the control key.
For instance, "C-d" means, hold down the control key and the
"d" key. (For Macs, "C" means the Apple button.)

C-d 
go down into the hierarchy after selecting the 
instance icon of some cell; 

C-u 
go back up. 

C-7 
Window.Zoom, i.e., zoom in.

C-0.
Winow.Zoom, i.e., zoom out.

C-i
Edit.Proporties.ObjectProperties, after selecting an object

C-e
Export.CreateExport, after selecting a pin

----------------------------
BASIC SVN COMMANDS
----------------------------
svn help     //-- display svn usage instructions
svn co       //-- get a working copy of a subtree of the repository
svn ci       //-- send changes in current subtree of working copy
svn add foo  //-- add existing local file/subdirectory to repository
svn rm foo   //-- remove a file/subdirectory locally and from repository
svn mv foo bar  //-- change "foo" to "bar" both locally and in repository
svn status   //-- report changes in current subtree waiting to be committed
svn up       //-- download changes from repository, update logs
svn log -v   //-- display log of committed changes made in current subtree
svn revert foo //-- undo changes in working copy

Usual working sequence:
-- svn up
-- (make changes locally)
-- svn up
-- svn status
-- svn ci
-- svn up