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

NB--Read this entire document BEFORE doing anything.
NB--In what follows, we will use "URL" to stand for,

        https://svn.cs.georgetown.edu/svn

For instance, the project sources introduced in class can be found at,

        URL/projects/LC3-trunk/


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

The above link is the URL for our Subversion (svn) repository
that holds project materials you will be using.  These include 
source files for the processor design, along with some tools 
and documentation. To get oriented, put the above address in 
a browser to check that you can get access to the repository. 
Notice the layout of LC3-trunk's sub-tree. You will be recreating
this structure in your svn branch. Read the READMEs at various
levels in the repository.

We will get to the following in more detail below. If you already have 
checked out URL/projects, 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. You will also "svn co" some parts of projects/LC3-trunk 
as sub-directories in your working copy. This is called a 
"nested checkout". For instance, suppose I did the following,

    cd
    svn co URL/projects2/120-2012fall/branches/rks
    cd rks
    mkdir trunk
    svn add trunk
    svn ci
    svn up
    cd trunk
    svn co URL/projects

I then would see src/ as a sub-directory of rks/trunk. If I then did 

    svn status 

I would see a line like this,

    ? trunk/src

which means that src/ is not a part of my branch, even though it
exists as a checked-out copy in my working copy. You can check what 
source is linked to a sub-directory in a working copy by doing,

    svn info

anywhere in the working copy's directory tree.

DO NOT "svn copy" any part of URL/projects into your branch. 
That doesn't work. When we mean for you to use the operating 
system's copy command, or equivalently to use a browser to download,
we will just say, "OS copy" or some such phrase.

We will be working in our 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,

    URL/projects/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,

    URL/projects2/120-2012/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",

    cd
    svn co URL/projects2/120-2012fall/branches/xy

where "xy" are your initials. Use the same username/password 
as you have been using. Your local copy is called a "working
copy" of your branch. Here, we'll use "xy" whenever we want to 
refer to your working copy.

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 xy

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. It is a very good idea to check in
your work frequently.

Next, create trunk/ as a sub-directory: e.g., use your OS command

    mkdir trunk

Do not use "svn mkdir". Your branch will then look like this:

         xy/
           trunk/

where I've listed the sub-directory below its parent directory. 
Then "svn add" trunk to your branch and check it in,

    cd
    cd xy
    svn up
    svn status
    svn ci
    svn up

where we do the "svn ci" if everything looks OK when we did
"svn status". The extra "svn up" updates our local copy of
the commit log. 

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

There are two reasons: 1) helps you know what you did.
2) helps me know who you are and what you did.
Both are important. See those comments with "svn -v log".
Sometimes, I may have to undo your mistakes.

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

To do "svn ci", you need to have an editor specified so that an
editing session can start as the first step of checking in. You
specify an editor to use during checkin by editing a file your
bash shell reads on startup, ".bash_profile" (or use ".bashrc"). 
This file is in your unix home directory (aka, "~"). You can
use a wysiwig Windows or OSX editor, if need be. Edit,

    .bash_profile

in your unix home directory. At the bottom of that file, add 
this line,

    export VISUAL=vi  

or, if you use emacs,

    export VISUAL=emacs

and save the file. Then do this in your unix shell,

    cd
    source .bash_profile
    echo $VISUAL

If all went well, you will see "vi" (or "emacs") displayed as
the value of your environment variable VISUAL. Svn will read
that variable to start up an editor during check in. (Aside,
to see the values of all your shell variables, do "set".)
-------------------------------------

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

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

    cd
    svn co URL/projects

Which will give you a local copy of that repository.
DO NOT "svn ci" or "svn import" in your copy of projects/.
ONLY   "svn up", which will get any modifications I may have made
to its contents. (Aside, NEVER DO "svn import" anywhere!)
Your unix home will now look something like this,

    ~/
        xy/               projects/
           trunk/                  LC3-tools/ LC3-trunk/

where sibling directories are listed below and right of the
parent directory.

========================
= Setting up your trunk
========================

Next, we will set up your local src/, bin/, and run/ directories.
We will also set up two directories, src2/ and lib/, which will
be "svn add"ed to your branch. After we've done all that, your working
copy will look like this,

         xy/
           trunk/
                 bin/  lib/   run/   src/  src2/

The temporary directories, bin/ and run/ need not be added to your 
branch as they contain local, temporary files. The src/ will also
not be added to your branch: it will be a copy from another
repository.

To get started, we will do what is called a "nested checkout": 
we will "svn co" URL/projects/LC3-trunk/src inside your working 
copy of your branch. 

DO NOT "svn add" src/ to your branch. The reason we check
it out is so that you can get updated versions of its contents
whenever I might need to make a change. You will do "svn up" inside
src/ to get any changes; you will NOT DO "svn ci" inside src/. 
Here's how we do the nested checkout,

    cd
    cd xy/trunk
    svn co URL/projects/LC3-trunk/src

Next, do this,

    cd
    cd xy
    svn status

You should see "? trunk/src/". This says that svn does not see
trunk/src/ as part of your branch, which is exactly right. When
you create new files or directories, you will also see "?" for
them. If you want them added to your branch, you "svn add". Just
don't add src/ or anything in src/.

Next, we will use src/ to build other parts of your branch. We
will do this by running "make" inside src/,

    cd src/
    make

You will see instructions on what to do next. The steps will create
your local run/ and bin/ directories. It also creates your src2/ source 
code directory and "svn add"s it to your branch. It will also set up 
your unix environment variable, PATH, so that executables put in your
bin/ can be found. In creating your local bin/, several tools will be 
compiled and their executables moved to your bin/.

Finally, we need to set up your own lib/ for your Electric source
libraries and add it to your branch. Here's what you do,

   cd
   cd xy
   svn up
   svn status
   cd trunk
   mkdir lib
   svn add lib
   cd ~/xy
   svn status
   svn ci
   
We do "svn status" to see what svn thinks it will do when we
do "svn ci". You should see "?" for those parts that are not
going to be added to your branch, "A" for those parts that
will be added, and "M" for any parts that were already part of
your branch and have been modified: the changes will be sent to 
the repository. If you see "C", you have a conflict and need to fix
it by hand (see LC3-trunk/docs/). A "!" means a file that is part 
of your branch is missing in your working copy.

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

First, get yourself your own copy of the tutorial,

    projects/LC3-trunk/examples/ElectricTutorial/tutorial.jelib

and copy into your trunk/lib/ and "svn add" it and "svn ci". Next,
if you don't already done it, OS copy,

    /projects/LC3-tools/electricBinary.jar 

to your trunk/bin/. Try running it to see that your system can execute 
it using

    java -jar electricBinary.jar

in a unix terminal window. You might also be able to run it by
double-clicking it from an OS 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
=======================

Next, create your own library from scratch by starting 
Electric without opening a library. Create cells and a simple 
hierarchical design and save the noname library in your trunk/lib/ as,

    myFirstLib.jelib. 

Create a verilog file from your design, 

    Electric.Tools.Simulation(Verilog).WriteVerilogDeck

and save it to your run/ directory. We will want to run iverilog,
but we need to update your environment variables, particularly your
PATH variable which locates executables. Executables will be in your 
trunk/bin/ and other places. 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 ==============================
====================================

------------------------------
= Lec-5-HW-2-ElectricShortcuts
------------------------------
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

------------------------------
Subversion clients: There are also GUI plug-ins and GUI standalone 
clients you can install on your system, but make sure you have 
a commandline svn client and learn how to use it.