Original GUI Installation Details

From Genesis2
Revision as of 00:27, 18 February 2012 by Shacham (talk | contribs) (1. Save the tarball)

Jump to: navigation, search

Where can I go to try it out?

Stanford GUI lives here: http://www-vlsi.stanford.edu/genesis

How do I install the GUI at my site?

The information below is taken from the file gui/configs/install/README.txt in the distribution tarball, where you will find the most up-to-date information.

0. Where to install

Installation should take place on the same machine that is running your web server. It might work better if you have root access and/or at least be running as the same user and group as the web server. Example:

 % ssh webserver -l root

OR

 % ssh webserver -l apache

If you don't have access to the webserver account, and/or if it doesn't even have an account, you can try to do the install as yourself. It's still a good idea to be on the webserver machine, however. And you'll probably need root access (e.g. sudo) to install the files in the right place and give the correct final permissions.

1. Save the tarball

Someone should have given you a compressed release tarball gui--r11111.tar.bz2. where r11111 is the revision number. Make a directory and put the tarball in it.

NOTE: Running from "/tmp" might help avoid permission problems. This is what I have to do to install at Stanford.

Example:

 % mkdir /tmp/unpackgui
 % mv gui.tar.gz /tmp/unpackgui

2. Unpack

Unpack the gui. Example:

 % cd /tmp/unpackgui
 % tar -xjf gui.tar.gz -C ./

You should see one file (README.txt) and one directory (gui).

 % ls -1F
 README.txt
 gui/

3. Upgrade existing install OR

If you are updating an existing installation, simply copy the new files in place of the old. For paranoia's sake, it's probably good to preserve a copy of the existing installation before overwriting it with the new update. For instance, at Stanford we would do:

 % cp -r /var/www/homepage/genesis ~/genesis.old
 % cd /tmp/unpackgui
 % cp -r gui/* /var/www/homepage/genesis

or maybe just

 % cp -rf gui/* /var/www/homepage/genesis

If updating, YOU ARE DONE, DO NOT PROCEED.

Otherwise, if this is a new install, move on to the next step, below.

4. New install

For a new install, cd to the install directory gui/configs/install. Run the install script INSTALL.sh and follow the directions. Note that you'll probably need to have full root privilege (e.g. sudo) for everything to work properly.

Okay, so here we go:

 % cd /tmp/unpackgui
 % cd gui/configs/install
 % sudo ./INSTALL.sh

of course, if you don't have access to sudo, you'll instead be doing something like

 % su root
 # ./INSTALL.sh


Note: By default the installation will create a website called "genesis," e.g. its URL will be "http://your-site.com/genesis" and the cgi files will live in e.g. "http://your-site.com/cgi/genesis". If for some reason you cannot use the default install name "genesis", and/or if you want to make a separate test installation with a different name you can do that by answering "yes" when prompt for changing the server dubdirectory. Only do that if you really know what you are doing. You can also use the "-test" option for INSTALL.sh, e.g.

 % cd /tmp/unpackgui
 % cd gui/configs/install
 % sudo ./INSTALL.sh -test genesis_test_install

Either way, these (above) would create a web site

   http://your-site.com/genesis_test_install

...instead of the default

   http://your-site.com/genesis


INSTALL.sh will want to know and/or will try to guess the following information (examples are from Stanford's installation at http://www-vlsi.stanford.edu/genesis - feel free to visit there for reference purposes):

  • what is your web-server URL (e.g. "http://www-vlsi.stanford.edu")
  • where do cgi files live on your server (e.g. "/usr/lib/cgi_bin")
  • what pathname does your server use to access cgi files (e.g. "/cgi-bin")
  • where do "/" level html files live on your server (e.g. "/var/www/homepage")
  • what is the username of the web server (e.g. "www-data")
  • what group name (for chgrp) can the web server access(e.g. "www-data")

5. Set permissions

Note the instructions at the end of the INSTALL script, which will tell you how to set correct permissions such that the web server can use the new installation. You'll be doing something like this:

 % chown -R www-data /var/www/homepage/genesis
 % chgrp -R www-data /var/www/homepage/genesis
 % chown -R www-data /usr/lib/cgi-bin/genesis
 % chgrp -R www-data /usr/lib/cgi-bin/genesis

6. Optional cleanup

Once installation is complete, you no longer need the contents of the unpacking directory, which can safely be deleted.

 % rm /tmp/unpackgui

How can I add my own Genesis design to the GUI?

1. Place your design in an appropriate location

First, you'll need a valid genesis design in a directory $DESIGNDIR that's accessible from the machine that's running your web werver. The directory should contain a valid makefile such that the GUI can make a copy of the makefile in an arbitrary clean directory, connect to that directory and do a "make" to create a new design. In particular, the makefile should produce a valid design when you do something like this:

 % mkdir /tmp/tmpdir17
 % cd /tmp/tmpdir17
 % cp $DESIGNDIR/Makefile .
 % ./make gen GENESIS_HIERARCHY=new.xml

If you don't know how to do this, talk to Ofer and/or see examples. (TODO: we don't currently have any examples!)

The design directory should contain at least one seed hierarchy file e.g. "baseline.xml", otherwise the user won't see any designs to modify. (TODO: this constraint should go away someday!)

2. Install the new design using the GUI itself OR

Direct your browser to the gui installed at your site, e.g. http://www.my-machine.com/genesis, and then click on the link that takes you to the design list; currently this is labeled something like "Click here to do real work."

This will take you to a page titled something like "Welcome to the Interactive Chip Generator!" At the bottom of the page is an "edit-design" link with a label something like "Click here to edit the design database." Click on this link.

Fill in the "Design name" and "Design location" text boxes with a unique name for your design and a pathname where the web server can find the design directory, e.g.

 design name: my_adder
 design location: /home/myname/my_adder/genesis

Design name can be anything, but I'd recommend sticking to alphanumerics plus underbars and/or hyphens for the name. The design location is the same as $DESIGNDIR discussed above, where the GUI should be able to find (using the above example) "/home/myname/my_adder/genesis/Makefile."

3. Edit the design file

You shouldn't have to edit the design list file directly, but you can if you want to. The GUI uses this file to find designs it can work on. The name of the file is site-dependent. You can find the name for your site by e.g. querying your CONFIG.TXT file, like so:

 % grep DESIGN_LIST /var/homepage/genesis/CONFIG.TXT
 DESIGN_LIST     /var/www/homepage/genesis/configs/design_list_stanford.txt

To add a new Genesis2 design to the gui, simply look at the DESIGN_LIST file and then edit it in the obvious way; refer to one of the existing design-list files as an example e.g. $GUI_HOME_DIR/configs/design_list_stanford.txt contains something like:

#################################################################
# SR designs
demo                          /home/steveri/demo
design0                       /home/steveri/tgt0
iterative_wallace_sr          /home/steveri/iterative_wallace_sr

The first column in a row is a unique name that you choose for your design; then whitespace; then the next column tells the GUI where find the design directory.

That's it! The new design should now magically appear in the GUI.

How do I build a new GUI release? (DEVELOPERS ONLY)

Use the existing release OR

There should be a copy of the latest release in the development path at this location:

 gui/configs/install/latest-release/gui.tar.gz

Build a new release

It's possible that the latest release could be missing or out of date and you'll want to build a new release. If so, follow the directions found in the development directory at $CHIPGEN/gui/configs/install/README-packing.txt, a current snapshot of which is provided below:

To build a new installation (developers only!!!),

 cd $CHIPGEN/gui/configs/install
 ./build_tarfile.sh

This will build a new compressed tarfile "/tmp/gui.tar.z" which should then be copied to "latest-release"

 cd ./latest-release
 mv gui.tar.gz gui.tar.gz.old
 mv /tmp/gui.tar.gz .

Test the release

(This information comes from $CHIPGEN/gui/configs/install/README-packing.txt, where you are likely to find the most up-to-date version.)

To test the installation-package process, login to vlsiweb and erase the old installation (if one exists). This does some scary stuff (like "sudo /bin/rm -rf"), so please make sure you know what you're doing! Note: no need to do this if /tmp/unpackgui doesn't exist.

 ssh vlsiweb
 cd /tmp/unpackgui
 sudo /bin/rm -rf /var/www/homepage/genesis_test_install /usr/lib/cgi-bin/genesis_test_install
 ls
 sudo /bin/rm -rf gui* R*

Then follow the directions in README.txt

 ssh vlsiweb
 mkdir /tmp/unpackgui
 cd /tmp/unpackgui
 cp ~/gui/configs/install/*/gui.tar.gz .
 gunzip -c gui.tar.gz | tar xf -
 cd gui/configs/install
 sudo ./INSTALL.sh -test

Verify the test install

Go to "http://www-vlsi.stanford.edu/genesis_test_install"; click on "Choose a design" and then "edit the design database"; enter design name "tgt0_example" and design location "/var/www/homepage/genesis_test_install/examples/tgt0" and then click "Submit" and then click "return to choose..."

Footnote

This information exists in two places:

 http://genesis2.stanford.edu/mediawiki/index.php?title=InteractiveGenesis2GUI
 $CHIPGEN/gui/configs/install/README-packing.txt

Links

See Genesis2 Main Page.

GUI To-Do List.