Original GUI Installation Details
- 1 Where can I go to try it out?
- 2 How do I install the GUI at my site?
- 3 How can I add my own Genesis design to the GUI?
- 4 How do I build a new GUI release? (DEVELOPERS ONLY)
- 5 Links
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
% 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.
% mkdir /tmp/unpackgui % mv gui.tar.gz /tmp/unpackgui
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
...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")
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:
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..."
This information exists in two places:
See Genesis2 Main Page.