Original GUI Installation Details

From Genesis2
Revision as of 18:44, 15 April 2015 by Steveri (talk | contribs) (PREVENT THE BOTS)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

(A.k.a InteractiveGenesis2GUI)


What's an "original GUI?"

There are three flavors of GUI:

  • The original GUI, designed to run under an existing web server installation such as apache;
  • Stewie the standalone GUI, designed to run in user space; and
  • Guisada (deprecated), which for development purposes can run the GUI perl scripts directly from the unix command line.

This article deals mainly with original GUI installation. For the others, see overview article Interactive Genesis2 GUI.

What's it look like when it's installed?

Check out Stanford's public GUI, which lives here: http://www-vlsi.stanford.edu/genesis

How do I install the GUI at my site?

It should be sufficient simply to run the INSTALL.sh script that comes with the GUI distribution. INSTALL.sh should walk you through the remaining steps enumerated below.

Install Genesis2 along with GUI source code

The original GUI will have been installed along with Genesis2 according to the Genesis2 installation instructions at http://genesis2.stanford.edu/mediawiki/index.php/Genesis2#Installing_Genesis2. The Genesis2 installation process should leave you with an environment variable "$GENESIS_HOME" such that your gui source will be found in a directory called "$GENESIS_HOME/gui".

Where to install the original GUI

Original-GUI 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


 % 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.

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
 % cp -r gui/* /var/www/homepage/genesis

or maybe just

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


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

New install

For a new install, cd to the install directory $GENESIS_HOME/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:

 % source ~/gui/configs/setup_stanford.cshrc  (I think) (to get $GENESIS_HOME etc.)
 % 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 subdirectory. Only do that if you really know what you are doing. You can also use the "-test" option for INSTALL.sh, e.g.

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

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


...instead of the default


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")

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


Once you've installed the gui, bots from Google, Baidu etc. will try and use it to recursively build millions of designs, generating verilog that will rapidly fill up your disk and crash your computer (oops). To prevent this, make sure you have installed a "robots.txt" file in the root of your www space. E.g. if http://yourmachine.com/ points to some directory /var/www/homepage/ you would install the robots.txt file as /var/www/homepage/robots.txt.

robots.txt should contain something like this:

User-agent: *
Disallow: /administrator/
Disallow: /cache/
Disallow: /components/
Disallow: /images/
Disallow: /includes/
Disallow: /installation/
Disallow: /language/
Disallow: /libraries/
Disallow: /media/
Disallow: /modules/
Disallow: /plugins/
Disallow: /templates/
Disallow: /tmp/
Disallow: /xmlrpc/
Disallow: /genesis/cgi/
Disallow: /cgi-bin/
Disallow: /cgi-bin/genesis/
Disallow: /cgi-bin/genesis_dev_sr/
Disallow: /cgi-bin/genesis.deleteme/
Disallow: /cgi-bin/genesis*/
Disallow: /cgi_bin/
Disallow: /cgi_bin/genesis/
Disallow: /cgi_bin/genesis_dev_sr/
Disallow: /cgi_bin/genesis.deleteme/
Disallow: /cgi_bin/genesis*/

To see the bots at work:

 % sudo cat /var/log/apache2/access.log | grep 'genesis.*xml' \
   | sed 's/.xml.*//' | cut -d ' ' -f 4,6,7 \
   | sed 's|.GET.*/designs/||' | uniq | less

or for more complete info just do:

 % sudo cat /var/log/apache2/access.log | grep 'genesis.*xml'

TO CLEAN UP AFTER THE BOTS this is useful:

 cd /var/www/homepage/genesis/designs/FloatingPointGen
 find . -mtime -4 -exec ls -lt {} \; | less
 mkdir deleteme
 sudo ls
 find . -mtime -4 -type f -exec sudo mv {} deleteme/ \;

Notes on installing the GUI at Stanford

In 2012 we updated vlsiweb and eventually I had to reinstall the GUI from scratch. Here are some of the problems I ran into:

Problem: vlsiweb genesis/gui directory is not up-to-date with latest development source


1. See what the differences are

 diff -r /var/www/homepage/genesis ~/smart_memories/Smart_design/ChipGen/bin/Genesis2Tools/gui

2. Maybe copy in the missing files from "Genesis2Tools" to "homepage"

3. Consider updating the official release in "/cad/genesis2," if necessary.

Problem: homepage no longer rooted at "/var/www/homepage/"


 cd /var/www/html
 ln -s ../homepage/genesis

Problem: Everything's in the wrong place (cad, cgi, homepage, ...)

Cannot find "/var/www/homepage" OR Cannot find cgi directory OR Cannot find cad directory OR Directory "/var/www/homepage" does not exist

Solution (vlsiweb):

 mkdir /var/www/homepage
 mkdir /usr/lib/cgi_bin
 ln -s /cad /hd/cad
 ln -s /var/www/homepage /var/www/html

New cgi is maybe /usr/lib/cgi-bin instead of prev /usr/lib/cgi_bin/genesis:

 cd /usr/lib/cgi-bin
 sudo ln -s /var/www/homepage/genesis/cgi genesis

My need to enable cgi and reboot the apache web server

 sudo a2enmod cgi
 sudo service apache2 restart

Directories must have correct permissions (root privilege)

 sudo chown root /var/www/homepage/
 sudo chown root /var/www/homepage/genesis/
 sudo chown root /var/www/homepage/genesis/cgi

Problem: TCL problems!!?? "init.c(478):ERROR:161: Cannot initialize TCL"

To reproduce:

 % /cad/modules/3.2.6/x86/bin/modulecmd tcsh load base
 init.c(478):ERROR:161: Cannot initialize TCL

Solved by using correct setup.cshrc file. Old/incorrect:

 source /cad/modules/init_modules.csh
 module load genesis2


 source /cad/modules/tcl/init/csh
 module load base
 module load genesis2

(Also updated tcllib but may not have been necessary):

 % sudo apt-get install tcllib
 % dpkg --get-selections | grep tcl
 libtcl8.6:amd64                                 install
 tcl                                             install
 tcl8.6                                          install
 tcllib                                          install

Problem: cgi directory does not work


1. cgi directory must exist:

 mkdir /usr/lib/cgi_bin
 ln -s /var/www/homepage/genesis/cgi/ /usr/lib/cgi-bin/genesis

2. cgi must be owned by root:

 % ls -ld /usr/lib/cgi-bin
 drwxr-xr-x 2 root root 4096 Dec 17 10:20 /usr/lib/cgi-bin/
 % ls -ld /usr/lib/cgi-bin/genesis
 lrwxrwxrwx 1 root root 29 Dec 17 09:22 /usr/lib/cgi-bin/genesis -> /var/www/homepage/genesis/cgi/
 % ls -ld /var/www/homepage/genesis/cgi
 drwxr-xr-x 3 root root 4096 Dec 17 14:23 /var/www/homepage/genesis/cgi/

Problem: Missing designs, missing design directory


Restore all the designs:

 cd /var/www/homepage/genesis
 sudo cp -r ~/gui/designs/* designs

Make them writable:

 cd /var/www/homepage/genesis
 sudo chown -R www-data designs
 sudo chgrp -R www-data designs

Problem: Missing perl package (XML/Simple):

 % perl -f /var/www/homepage/genesis/cgi/updatedesign.dir/build_xml_change_file.pl
 Can't locate XML/Simple.pm in @INC (you may need to install the
 XML::Simple module) (@INC contains: ...) at
 line 5.
 BEGIN failed--compilation aborted at
 line 5.


 cpan App::cpanminus
 cpanm XML::Simple

Problem (FPGen): Missing file "demo/fpdemo.php" and dir "designs/FloatingPointGen/"


 cd /var/www/homepage/genesis
 sudo cp -r ~steveri/gui/demo/ .
 sudo cp -r ~steveri/gui/designs/FloatingPointGen/ .

Problem (FPGen demo): Missing file "designs/FloatingPointGen/FPGen.js"


  1. Added file-exists check to fpdemo.php.
  2. cd designs/FloatingPointGen; cp empty.js FPGen.js

Problem (FFT): "do_anything.pl" missing from cgi directory


 sudo cp /home/steveri/gui/cgi/do_anything.pl /var/www/homepage/genesis/cgi
 ls !$
 sudo chown www-data /var/www/homepage/genesis/cgi/*
 sudo chgrp www-data /var/www/homepage/genesis/cgi/*

Problem (Stewie): "Can't locate HTTP/Server/Simple/CGI.pm"


1. If not done already, install cpanminus:

 cpan App::cpanminus

2. Install missing package (don't use sudo)

 cpanm HTTP::Server::Simple::CGI

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

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!)

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."

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. $GENESIS_HOME/gui/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)

  • Short answer: "./build_release.sh"
  • Long answer: see below.

Note: This information exists in two places:

Build the release

If you just want the latest source tarball, there should be one in the development path at this location:


To build a new tarball and/or a complete new release, do this:

 cd $CHIPGEN/gui/configs/install
 ssh neva

Note that "build_release" only works on neva, because of permission problems with respect to final install location "/cad".

Test the release

To be safe, we'll use a test location "homepage/genesis_text_install" to test the release, instead of the official final home "homepage/genesis".

Out with the old

To test the installation-package process, login to vlsiweb and erase the old installation (if one exists), as shown below. This does some scary stuff (like "sudo /bin/rm -rf"), so please make sure you know what you're doing!

 ssh vlsiweb
 sudo /bin/rm -rf /var/www/homepage/genesis_test_install /usr/lib/cgi-bin/genesis_test_install

In with the new

At Stanford:

 ssh vlsiweb
 sudo /bin/rm -rf /tmp/unpackgui
 mkdir /tmp/unpackgui
 cd /tmp/unpackgui
 cp ~/gui/configs/install/*/gui.tar.bz2 .
 tar xjf gui.tar.bz2
 cd /tmp/unpackgui/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..."