Difference between revisions of "Original GUI Installation Details"

From Genesis2
Jump to: navigation, search
(4. New install)
(PREVENT THE BOTS)
 
(115 intermediate revisions by 2 users not shown)
Line 1: Line 1:
== Where can I go to try it out? ==
+
<i><small>(A.k.a [[InteractiveGenesis2GUI]])<br></small></i>
  
Stanford GUI lives here: http://www-vlsi.stanford.edu/genesis
+
= What's an "original GUI?" =
  
== How do I install the GUI at my site? ==
+
There are three flavors of GUI:
 +
* The <b>original GUI</b>, designed to run under an existing web server installation such as apache;
 +
* <b>Stewie the standalone GUI</b>, designed to run in user space; and
 +
* <b>Guisada</b> (deprecated), which for development purposes can run the GUI perl scripts directly from the unix command line.
  
The information below is taken from the file <tt>gui/configs/install/README.txt</tt> in the distribution tarball, where you will find the most up-to-date information.
+
This article deals mainly with <b>original GUI</b> installation.
 +
For the others, see overview article [[Interactive Genesis2 GUI]].
  
=== 0. Where to install ===
+
= What's it look like when it's installed? =
  
Installation should take place on the same machine that is running
+
Check out Stanford's public GUI, which lives here: http://www-vlsi.stanford.edu/genesis
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
+
= How do I install the GUI at my site? =
  
OR
+
It should be sufficient simply to run the <b><tt>INSTALL.sh</tt></b> script that comes with the GUI distribution.  <b><tt>INSTALL.sh</tt></b> should walk you through the remaining steps enumerated below.
  
  % ssh webserver -l apache
+
== Install Genesis2 along with GUI source code ==
  
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, howeverAnd you'll probably need root access (e.g. <tt>sudo</tt>) to install the files in the right place and give the correct final permissions.
+
The <b>original GUI</b> will have been installed along with Genesis2 according to the [[Genesis2#Installing_Genesis2 | Genesis2 installation instructions]] at http://genesis2.stanford.edu/mediawiki/index.php/Genesis2#Installing_Genesis2The Genesis2 installation process should leave you with an environment variable
 +
"<tt>$GENESIS_HOME</tt>"
 +
such that your gui source will be found in a directory called
 +
"<tt>$GENESIS_HOME/gui</tt>".
  
=== 1. Save the tarball ===
+
== Where to install the original GUI ==
 
 
Someone should have given you a compressed release tarball <b><tt>gui.tar.gz.</tt></b>  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.
 
  
 +
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:
 
Example:
  
   % mkdir /tmp/unpackgui
+
   % ssh webserver -l root
  % mv gui.tar.gz /tmp/unpackgui
 
  
=== 2. Unpack ===
+
or
Unpack the gui.  Example:
 
  
   % cd /tmp/unpackgui
+
   % ssh webserver -l apache
  % gunzip -c gui.tar.gz | tar xvf -
 
 
 
You should see one file (<tt>README.txt</tt>) and one directory (<tt>gui</tt>).
 
  
  % ls -1F
+
If you don't have access to the webserver account, and/or if it
  README.txt
+
doesn't even have an account, you can try to do the install as
  gui/
+
yourself. It's still a good idea to be on the webserver machine,
 +
however.  And you'll probably need root access (e.g. <tt>sudo</tt>) to
 +
install the files in the right place and give the correct final
 +
permissions.
  
=== 3. Upgrade existing install OR ===
+
== Upgrade existing install OR ==
 
If you are updating an existing installation, simply copy the new
 
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
 
files in place of the old.  For paranoia's sake, it's probably good
Line 52: Line 53:
  
 
   % cp -r /var/www/homepage/genesis ~/genesis.old
 
   % cp -r /var/www/homepage/genesis ~/genesis.old
   % cd /tmp/unpackgui
+
   % cd $GENESIS_HOME
 
   % cp -r gui/* /var/www/homepage/genesis
 
   % cp -r gui/* /var/www/homepage/genesis
  
Line 63: Line 64:
 
Otherwise, if this is a new install, move on to the next step, below.
 
Otherwise, if this is a new install, move on to the next step, below.
  
=== 4. New install ===
+
== New install ==
 
For a new install, cd to the install directory
 
For a new install, cd to the install directory
<tt>gui/configs/install</tt>.  Run the install script
+
<tt>$GENESIS_HOME/gui/configs/install</tt>.  Run the install script
 
<tt>INSTALL.sh</tt> and follow the directions.
 
<tt>INSTALL.sh</tt> and follow the directions.
 
Note that you'll probably need to have full root privilege (e.g. <tt>sudo</tt>) for everything to work properly.
 
Note that you'll probably need to have full root privilege (e.g. <tt>sudo</tt>) for everything to work properly.
Line 71: Line 72:
 
Okay, so here we go:
 
Okay, so here we go:
  
   % cd /tmp/unpackgui
+
   % source ~/gui/configs/setup_stanford.cshrc  (I think) (to get $GENESIS_HOME etc.)
 +
  % cd $GENESIS_HOME
 
   % cd gui/configs/install
 
   % cd gui/configs/install
 
   % sudo ./INSTALL.sh
 
   % sudo ./INSTALL.sh
Line 81: Line 83:
  
  
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 <i>server dubdirectory</i>. Only do that if you really know what you are doing. You can also use the "-test" option for INSTALL.sh, e.g.
+
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 <i>server subdirectory</i>. 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 $GENESIS_HOME
 
   % cd gui/configs/install
 
   % cd gui/configs/install
 
   % sudo ./INSTALL.sh -test genesis_test_install
 
   % sudo ./INSTALL.sh -test genesis_test_install
Line 106: Line 108:
 
* what group name (for <tt>chgrp</tt>) can the web server access(e.g. "<tt>www-data</tt>")
 
* what group name (for <tt>chgrp</tt>) can the web server access(e.g. "<tt>www-data</tt>")
  
=== 5. Set permissions ===
+
== Set permissions ==
 
Note the instructions at the end of the INSTALL script, which will  
 
Note the instructions at the end of the INSTALL script, which will  
 
tell you how to set correct permissions such that the web server  
 
tell you how to set correct permissions such that the web server  
Line 117: Line 119:
 
   % chgrp -R www-data /usr/lib/cgi-bin/genesis
 
   % chgrp -R www-data /usr/lib/cgi-bin/genesis
  
=== 6. Optional cleanup ===
+
== PREVENT THE BOTS ==
Once installation is complete, you no longer need the contents of
+
 
the unpacking directory, which can safely be deleted.
+
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 <tt>/var/www/homepage/</tt> you would install the <tt>robots.txt</tt> file as <tt>/var/www/homepage/robots.txt</tt>.
  
  % rm /tmp/unpackgui
+
<tt>robots.txt</tt> should contain something like this:
  
== How can I add my own Genesis design to the GUI? ==
+
<pre>
 +
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*/
 +
</pre>
  
=== 1. Place your design in an appropriate location ===
+
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 ====
 +
'''Solution:'''
 +
 
 +
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/" ====
 +
 
 +
'''Solution:'''
 +
  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
 +
 
 +
New/correct:
 +
  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 ====
 +
'''Solution:'''
 +
 
 +
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 ====
 +
'''Solution:'''
 +
 
 +
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
 +
  /var/www/homepage/genesis/cgi/updatedesign.dir/build_xml_change_file.pl
 +
  line 5.
 +
 
 +
  BEGIN failed--compilation aborted at
 +
  /var/www/homepage/genesis/cgi/updatedesign.dir/build_xml_change_file.pl
 +
  line 5.
 +
 
 +
'''Solution:'''
 +
  su
 +
  cpan App::cpanminus
 +
  cpanm XML::Simple
 +
 
 +
==== Problem (FPGen): Missing file "demo/fpdemo.php" and dir "designs/FloatingPointGen/" ====
 +
 
 +
'''Solution:'''
 +
  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" ====
 +
 
 +
'''Solution:'''
 +
# Added file-exists check to fpdemo.php.
 +
# <tt>cd designs/FloatingPointGen; cp empty.js FPGen.js</tt>
 +
 
 +
==== Problem (FFT): "do_anything.pl" missing from cgi directory ====
 +
 
 +
'''Solution:'''
 +
  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" ====
 +
 
 +
'''Solution:'''
 +
 
 +
1. If not done already, install cpanminus:
 +
  su
 +
  cpan App::cpanminus
 +
 
 +
2. Install missing package  (don't use sudo)
 +
  su
 +
  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 <tt>$DESIGNDIR</tt> that's accessible from the machine that's running your web werver.
 
First, you'll need a valid genesis design in a directory <tt>$DESIGNDIR</tt> that's accessible from the machine that's running your web werver.
Line 138: Line 339:
 
<b>(TODO: we don't currently have any examples!)</b>
 
<b>(TODO: we don't currently have any examples!)</b>
  
 +
<!--
 
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.
 
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!)'''
 
'''(TODO: this constraint should go away someday!)'''
 +
(it went away)
 +
-->
  
=== 2. Install the new design using the GUI itself <b>OR</b> ===
+
== Install the new design using the GUI itself <b>OR</b> ==
  
 
Direct your browser to the gui installed at your site,  
 
Direct your browser to the gui installed at your site,  
Line 159: Line 363:
 
"<tt>/home/myname/my_adder/genesis/Makefile.</tt>"
 
"<tt>/home/myname/my_adder/genesis/Makefile.</tt>"
  
=== 3. Edit the design file ===
+
== Edit the design file ==
  
 
You shouldn't have to edit the design list file directly, but you can if you want to.
 
You shouldn't have to edit the design list file directly, but you can if you want to.
Line 167: Line 371:
 
   DESIGN_LIST    /var/www/homepage/genesis/configs/design_list_stanford.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:
+
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. <tt>$GENESIS_HOME/gui/configs/design_list_stanford.txt</tt> contains something like:
  
 
  #################################################################
 
  #################################################################
Line 179: Line 383:
 
That's it!  The new design should now magically appear in the GUI.
 
That's it!  The new design should now magically appear in the GUI.
  
== How do I build a new GUI release? (DEVELOPERS ONLY) ==
+
= How do I build a new GUI release? (DEVELOPERS ONLY) =
 
+
* Short answer: "./build_release.sh"
=== Use the existing release OR ===
+
* Long answer: see below.
  
There should be a copy of the latest release in the development path at this location:
+
<small><i>Note: This information exists in two places:
 +
* http://genesis2.stanford.edu/mediawiki/index.php/Original_GUI_Installation_Details#How_do_I_build_a_new_GUI_release.3F_.28DEVELOPERS_ONLY.29
 +
* $GENESIS_HOME/README-packing.txt
 +
</i></small>
  
  gui/configs/install/latest-release/gui.tar.gz
+
== Build the release ==
  
=== Build a new release ===
+
If you just want the latest source tarball, there should be one in the development path at this location:
  
It's possible that the latest release could be missing or out of
+
  $CHIPGEN/gui/configs/install/latest-release/gui.tar.bz2
date and you'll want to build a new release.  If so, follow the
 
directions found in the development directory at
 
<tt>$CHIPGEN/gui/configs/install/README-packing.txt</tt>,
 
a current snapshot of which is provided below:
 
  
To build a new installation (developers only!!!),
+
To build a new tarball and/or a complete new release, do this:
  
 
   cd $CHIPGEN/gui/configs/install
 
   cd $CHIPGEN/gui/configs/install
 
   ./build_tarfile.sh
 
   ./build_tarfile.sh
 +
  ssh neva
 +
  ./build_release.sh
  
This will build a new compressed tarfile "/tmp/gui.tar.z" which should
+
Note that "build_release" only works on neva, because of permission
then be copied to "latest-release"
+
problems with respect to final install location "/cad".
  
  cd ./latest-release
+
== Test the release ==
  mv gui.tar.gz gui.tar.gz.old
 
  mv /tmp/gui.tar.gz .
 
  
=== 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".
  
(This information comes from
+
=== Out with the old ===
<tt>$CHIPGEN/gui/configs/install/README-packing.txt</tt>,
 
where you are likely to find the most up-to-date version.)
 
  
 
To test the installation-package process, login to vlsiweb and erase  
 
To test the installation-package process, login to vlsiweb and erase  
the old installation (if one exists).  This does some scary stuff
+
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!
 
(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
 
   ssh vlsiweb
  cd /tmp/unpackgui
 
 
   sudo /bin/rm -rf /var/www/homepage/genesis_test_install /usr/lib/cgi-bin/genesis_test_install
 
   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
+
=== In with the new ===
 +
 
 +
At Stanford:
  
 
   ssh vlsiweb
 
   ssh vlsiweb
 +
  sudo /bin/rm -rf /tmp/unpackgui
 
   mkdir /tmp/unpackgui
 
   mkdir /tmp/unpackgui
 +
 
   cd /tmp/unpackgui
 
   cd /tmp/unpackgui
   cp ~/gui/configs/install/*/gui.tar.gz .
+
   cp ~/gui/configs/install/*/gui.tar.bz2 .
   gunzip -c gui.tar.gz | tar xf -
+
   tar xjf gui.tar.bz2
   cd gui/configs/install
+
 
 +
   cd /tmp/unpackgui/gui/configs/install
 
   sudo ./INSTALL.sh -test
 
   sudo ./INSTALL.sh -test
  
==== Verify the test install ====
+
=== Verify the test install ===
  
 
Go to "http://www-vlsi.stanford.edu/genesis_test_install";
 
Go to "http://www-vlsi.stanford.edu/genesis_test_install";
Line 242: Line 445:
 
and then click "Submit" and then click "return to choose..."
 
and then click "Submit" and then click "return to choose..."
  
=== Footnote ===
+
= Links =
 
 
This information exists in two places:
 
  http://genesis2.stanford.edu/mediawiki/index.php?title=InteractiveGenesis2GUI
 
  $CHIPGEN/gui/configs/install/README-packing.txt
 
 
 
== Links ==
 
 
 
See [http://genesis2.stanford.edu/mediawiki/index.php/Main_Page#Genesis2 Genesis2 Main Page].
 
  
[https://www-vlsi.stanford.edu/mediawiki/index.php/CG/GUI_To-Do_List GUI To-Do List].
+
* [http://genesis2.stanford.edu/mediawiki/index.php/GUI_Links Complete list of GUI-related links].

Latest revision as of 18:44, 15 April 2015

(A.k.a InteractiveGenesis2GUI)

Contents

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

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.

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

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 $GENESIS_HOME
 % 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 $GENESIS_HOME
 % 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")

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

PREVENT THE BOTS

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

Solution:

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

Solution:

 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

New/correct:

 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

Solution:

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

Solution:

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
 /var/www/homepage/genesis/cgi/updatedesign.dir/build_xml_change_file.pl
 line 5.
 
 BEGIN failed--compilation aborted at
 /var/www/homepage/genesis/cgi/updatedesign.dir/build_xml_change_file.pl
 line 5.

Solution:

 su
 cpan App::cpanminus
 cpanm XML::Simple

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

Solution:

 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"

Solution:

  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

Solution:

 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"

Solution:

1. If not done already, install cpanminus:

 su
 cpan App::cpanminus

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

 su
 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:

 $CHIPGEN/gui/configs/install/latest-release/gui.tar.bz2

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

 cd $CHIPGEN/gui/configs/install
 ./build_tarfile.sh
 ssh neva
 ./build_release.sh

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

Links