#------------------------------------
#-- Lec-1-HW-2
#------------------------------------
NB--Read this entire document BEFORE doing anything.
The project sources introduced in class can be found here:
https://svn.cs.georgetown.edu/svn/projects/LC3-trunk
(1.)===========================
The above link is the URL for our Subversion (svn) repository
holding the project materials you will be using. When you need any
of this material, download it using a web browser. These include
the sources files for the processor design, along with some tools
and documentation. To get oriented, put the above URL in a browser
window to check that you can get access to the repository.
Notice the layout of the trunk's sub-tree. You will be recreating
this structure in you svn branch. Read the READMEs at the
top level.
(2.) The top level is "projects/LC3-trunk". Below you will find
a "docs/" subdirectory. In there, you will find information on
the various files and tools needed for our LC3 project.
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/".
(2.1)===========================
If you are not familiar with unix, read docs/README-unix,
and install cygwin, if needed. Your own branch has been created
for you in a second repository which uses the same username/password:
https://svn.cs.georgetown.edu/svn/projects2/120-2011fall/branches
Your sub-directory under branches/ is named by your UIS id.
Check out a working copy of your branch on whatever machine you
are going to use for the project. "cd" to where you want to put your
working copy and "svn co",
svn co https://svn.../projects2/120-2011fall/branches/
where "" is your UIS id. You can have multiple working
copies on different machines simultaneously. You can delete a working
copy at any time this way,
rm -rf
but make sure you keep the repository up-to-date. Create a "docs/"
directory in your working copy using unix "mkdir". Do not "svn add"
docs/ to your branch: you will not be making changes to this directory.
Using a browser to access LC3-trunk/, you may download the contents of
the trunk/docs/ to your branch's docs/.
[but see NOTES below for an alternative].
(2.2)=======================
Also, create bin/, run/, lib/, and src/ sub-directories. Your branch
will then look like this:
projects2
branches
rks
trunk
bin docs lib run src
where sub-directories are listed below their parent directory.
Copy examples/ElectricTutorial/tutorial.jelib into your lib directory.
Next, if you don't already have it, download
projects/LC3-tools/electricBinary-9.00.jar
to your bin/. Try running it to see that your system can execute it using
java -jar electricBinary-9.00.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.
You can run it by either double-clicking it in your system's
(2.3)==============================
Open your examples/ElectricTutorial/tutorial.jelib in Electric using,
Electric.File.OpenLibrary
It may take some navigating (scroll up to see parent directories)
to find your lib/. Work your way through the tutorial just until you
feel you have the hang of using Electric (see the README cell in
tutorial.jelib). 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 as
lib/myFirstLib.jelib.
Create a verilog file from your design, and save it to your run directory.
(3.)=====================================
In a unix terminal window,
cd
which will put you in your home directory. If you are on a Windows
machine, cygwin and Windows do not agree on the shape of the directory
tree of the entire file system. You can get to "C:\" in cygwin with,
cd /cygdrive/c/
Note that you have two home directories: (1) your cygwin home which
is in /home, and your Windows home, which is in
/cygdrive/c/Users/
It can get confusing. It is best to keep your work in /home.
Assuming you are in your unix home, we need to update our environment
variables. For running Electric, it is best to cd to the bin/
directory and run it from there on the commandline. Other executables
will be in your bin/ or other places. For instance, iverilog is in
/cygdrive/c/cygwin/bin
if you took all defaults when installing on a Windows machine. On
a unix machine, depending on how you installed it, it is someplace.
You might not know where. Here's how you can find it,
find . -name "iverilog"
The "." means start searching from the current directory; so, you
should cd to someplace up in the file system tree to start searching.
"find" will search everywhere below where it is started. This could
take quite a while if you start at "/", 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 and saving
the changes, if you exit your shell and log in again, your
PATH variable will have that path pre-pended. You can check this with,
echo $PATH
You can see the values of all your shell's variables with,
set
Setting your executable search path, 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. Note that if an
executable is in your current directory, you can use,
./foobar
where "foobar" is the name of the executable, without setting your PATH.
NOTES==============================
(0.)----------------------------
BASIC SVN COMMANDS
svn help //-- display svn usage instructions
svn co //-- get a working copy of a subtree of the repository
svn ci //-- send/commit changes made in current subtree of working copy
svn add foo //-- add existing local file/subdirectory to repository
svn del foo //- remove a file/subdirectory locally and from repository
svn ren foo bar //-- change the name of "foo" to "bar" both locally and in repository
svn status //-- report changes made 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, restore to previous repository version
Usual working sequence:
-- svn up
-- (make changes locally)
-- svn up
-- svn status
-- svn ci
-- svn up
(1.)----------------------------
Downloading /docs: Using the web browser you can right-click
(or Apple-click) on a file and "Save link as" or "Save target as"
to download the file. This is a bit tedious, but gets you what
you need. You can simplify the process by doing,
svn co https://svn.../LC3-trunk/docs
This is a new checkout in an already existing working directory,
a "nested" checkout. When you do,
svn status
the result will depend on where you are in your working copy. If
you are in docs/, you are not in your branch. If you are higher up,
you will see docs/ listed with a "?" preceding it. Your branch
does not know about docs/ because it is not part of your branch.
DO NOT "svn add docs/" to your branch. There are two reasons: (1) it
won't work correctly, (2) you will defeat the advantage of having
checked it out--you will not receive updated documentation via
"svn up" when you are in docs/.
(2.)------------------------------
Subversion clients: There also GUI plug-ins and GUI standalone
clients you can install on your system, but make sure you have
a commandline client and learn how to use it.
(3.)------------------------------
Learning unix, and/or vi. There are a couple of READMEs in docs/.
Also see the README-unix-shell-vi-veryShortIntro.
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.