Getting Started
From UIDWiki
Contents |
Get Permissions
First, you need a CSAIL account. Get Rob's help to get one.
Once you have a CSAIL account, get a CSAIL certificate in your web browser. This will give you permission to edit our wiki and bug database.
You will also need to be a member of the UID Kerberos protection group, which will give you permission to our Subversion repository. Get Rob's help to add you:
pts adduser -group uid -user username
Join the Mailing Lists
Join our mailing lists:
- uid list is for general messages to everybody in the User Interface Design group.
- chickenfoot-developers is for people working on Chickenfoot. It also gets messages from users of Chickenfoot out on the net.
Edit the wiki
Log in to this wiki (using your CSAIL certificate).
After you've logged in, go to your personal page (by clicking on your username in the upper-right corner of the page) and edit it. Add a message about yourself. Start taking notes on the page as you work through the rest of these instructions.
Get the Tools
Collect the tools you need to compile our code. These tools are already installed on CSAIL and Athena workstations, but you may need to adjust your search path to point to them, by following the instructions below. If you want to work on your home machine, you may need to download these tools and install them locally.
Java JDK 6. On CSAIL workstations, you get Java by creating a text file ~/.software containing the single line:
java2
Log out of your CSAIL account and log back in, and test that you can run it:
java -version
On Athena, you get Java by running add -f java. You can get a specific version with add -f java_v1.5.0_02.
On Windows, you can download Java from Sun.
Eclipse 3.2. Eclipse is the IDE we use to develop Java code. It includes CVS access, a source-level debugger, and some nice code refactoring support. Eclipse runs on Linux, Windows, and Mac OS.
CSAIL: Add the line "eclipse" to ~/.software, log out and log in Athena: add eclipse-sdk ; eclipse Windows: Download Eclipse
Subclipse. Subclipse is an Eclipse plugin for Subversion, the version control system we're using. Without this plugin, you won't be able to check out Chickenfoot.
- In Eclipse, go to Help -> Software Updates -> Find and Install... >> Search for new features to install.
- New Remote Site >> Name: Subclipse, URL: http://subclipse.tigris.org/update_1.2.x
- Press Next to scan for updates; when the scan is done, select Subclipse and install it.
- Restart Eclipse.
Mozilla Firefox. This is the web browser that our Chickenfoot plugin works with. You should have Firefox 2.0 or later.
CSAIL: Version 1.0 is the CSAIL default; see below... Athena: add firefox ; firefox Windows: Download Firefox.
To install Firefox 2.0 on a CSAIL workstation which runs 1.0:
- Per instructions at backports.org, at the end of /etc/apt/sources.list, add the line
deb http://www.backports.org/debian sarge-backports main contrib non-free - apt-get update
- apt-get install firefox and agree to uninstall package mozilla-firefox in the process
- Start Firefox
Other tools. Here are some of the other tools we use. Installing them is optional, and if you're just getting started with the UID group, you should skip these for now.
- Cygwin: install this on your Windows machine so that you have access to Unix tools like diff, zip, and command-line SVN. CSAIL and Athena don't need it, since they already have Unix tools. When Cygwin offers you a long list of packages to install, it's a good idea to make sure that openssh and subversion are being installed, since these are useful.
- Apache Ant: the build tool that we use. Ant is included in Eclipse, so you only need to download it separately if you want to run Ant from the command line. On CSAIL, Ant is installed at /afs/csail/group/uid/tools/ant/bin/ant, and on Athena at add 6.170 ; ant.
- Subversion: the command-line client for Subversion. It's easier to use the Subclipse plugin that you already installed above, but the command-line client is a good fallback in case the plugin doesn't work. CSAIL already has the client installed. On Windows, Subversion can be installed as part of Cygwin.
Configure Firefox
There are a few things you need to do to your Firefox installation to make developing and debugging Chickenfoot easier. Do them now:
Make sure you have the DOM Inspector. The DOM Inspector is used for looking at HTML and XUL element trees. You should find it on the Tools menu. If you don't have it, then download and install Firefox again, and in the installation process, when it asks you if you want a custom installation, say Yes. That should get you the DOM Inspector.
Create a Chickenfoot profile in Firefox. This will allow you to isolate your Chickenfoot development from your ordinary browsing. Using Start / Run, run firefox -profilemanager (or enter firefox -ProfileManager into the terminal on UNIX-based machines) to bring up the Firefox profile manager. Create a profile named Chickenfoot. The Firefox configuration steps below will affect only the current profile, so make sure you're running the Chickenfoot profile when you do them.
Turn on Javascript errors for extensions. Normally the Javascript console only displays errors for web pages, not for Firefox or its extensions. Go to the URL about:config and turn on javascript.options.showInConsole.
Learn how to open the Javascript and Java consoles. Javascript errors go to the Javascript console, which is found on the Tools menu. Java exceptions (and standard output/error) go to the Java console, which (on Windows) can be opened from Java's system tray icon, which appears when the Java plugin starts.
Install Firebug. Firebug is an excellent debugger for Javascript in HTML pages. Unfortunately it can't debug Javascript used in Firefox extensions (like Chickenfoot), but it does a good job of helping you explore HTML pages. It's better than the DOM inspector for that.
Configure Your Development Environment
There are a few things you need to do to set up your editor or IDE. Do them now:
Install syntax-coloring and autoindentation for Javascript. For Eclipse, most of us use Colorer, which you can get like this:
- Go to Help / Software Updates / Find & Install.
- Select Search for new features to install.
- Click New Remote Site and fill in Name: Colorer and URL http://colorer.sf.net/eclipsecolorer/
- Proceed through the install wizard, making sure to check the checkbox for Colorer each time you're given a choice (you'll have to do it twice).
- Restart Eclipse after Colorer is installed.
- After restarting Eclipse, go to Window / Preferences... and then General / Editors / File Associations. Make sure that Java Editor is still your default editor for *.java files, and not Colorer (or else you lose all the advantages of Eclipse's Java editor).
- While you're there, add Colorer as the default editor for *.rdf, *.sh, and *.xul. (It should already be setup for JavaScript, XML, HTML, and CSS.)
Always change tabs to spaces in source files. We don't want tab characters in text files in CVS, because different editors and tools interpret tabs differently. All indentation should be done purely with spaces. Our Subversion repository will actually reject commits that include tabs in text files, so you'd better fix this now, or face pain later.
To change tabs to spaces in Eclipse, change these preferences:
- Go to Window / Preferences / Java / Code Style / Formatter / Edit... / Indentation. Pull down the dropdown menu for Tab Policy and select "Spaces only."
- Go to Window / Preferences / Ant / Editor / Formatter, and uncheck "Use tab character instead of spaces".
- If you installed Colorer, go to Window / Preferences / Colorer Library Editor / Uses spaces instead of tabs.
For Emacs (if you use it for editing code), put the following line in your ~/.emacs file:
(setq-default indent-tabs-mode nil)
For Vim (if you use it for editing code), put the following in your ~/.vimrc file:
set expandtab " Use spaces instead of tabs set autoindent " Inherit indent from previous line set tabstop=2 " Display \t as 2 spaces set shiftwidth=2 " Number of spaces to use for each indent set softtabstop=2 " Treat 2 spaces as a tab for editing purposes set smarttab " Insert blank space at beginning of line with tab
Check Out the Project
Configure Subclipse to use its internal svn client. Go to Window >> Preferences >> Team >> SVN and select JavaSVN (Pure Java).
Check out the project. Our latest projects, like Chickenfoot, are stored in Subversion. If you're using Eclipse, you'll need to open either the SVN Repositories view and right-click on it to add the repository location below. If you're using command-line tools, use svn checkout with the location below.
svn+ssh://svn.csail.mit.edu/afs/csail/group/uid/svn/uid
If you look inside this repository, you'll see three root folders:
projects/ for shared group projects like Chickenfoot and Kangaroo papers/ for papers and talks users/ for personal projects by UID group members
Older projects, like LAPIS, are stored in CVS. In Eclipse, go to the CVS Repositories view and right-click on it to add the location below.
CVS Host: login.csail.mit.edu Pathname: /afs/csail/group/uid/cvs
If you need to build the LAPIS-Chickenfoot bridge, check out LAPIS from CVS, and check out lapis-chickenfoot from Subversion. Make the two directories siblings in the directory tree so that lapis-chickenfoot/ can find lapis by going to ../lapis.
Build the Project
Look for error messages. Assuming you're using Eclipse, all the Java code in the LAPIS and Chickenfoot projects is compiled automatically when you check it out, and whenever you make an edit. But if you see lots of error messages, you may need to modify your compiler settings. LAPIS and Chickenfoot use Java 1.5 features, but Eclipse's default settings may not allow them. To fix this, do the following:
- Go to Window / Preferences / Java / Compiler.
- For Compiler compliance level, select 5.0.
Even after doing this, you may still see a lot of warnings ("Type safety:..."), but this is OK.
Build the project. Right-click on chickenfoot/build.xml and select Run / Ant Build.
Run the Project
One way to run Chickenfoot is to start Firefox and use File >> Open File to open chickenfoot/build/chickenfoot.xpi. But this would be painful to do every time you recompile Chickenfoot, so we have a faster way.
Create firefox.properties. In your chickenfoot project, copy the file firefox-default.properties and name the new copy firefox.properties. Edit the file so that it contains the correct paths to Firefox on your platform. Most of the defaults in the file are probably correct for Windows, but you'll have to find your Firefox profile directory. Follow the instructions in the file.
Create a Chickenfoot profile. The default firefox.properties assumes you want to create a new Firefox profile just for developing Chickenfoot, called Chickenfoot. This is useful, particularly if you depend on Firefox for your web browsing, because it means that bugs in Chickenfoot won't affect your existing default profile.
The first time you run firefox -P Chickenfoot (to start Firefox in the Chickenfoot profile), Firefox will pop up the Profile Manager instead, since the Chickenfoot profile doesn't exist. You should create a profile named Chickenfoot manually. Once the profile is created, the build script will use it automatically from then on, and you won't have to deal with the Profile Manager.
Run Chickenfoot. Once you've configured firefox.properties, you can run Firefox & Chickenfoot directly from Eclipse. Right-click on build.xml and choose Run / Ant Build... Check the "run-no-install" target. Uncheck the "build" target (since "run-no-install" will do a build automatically), and press OK. After Chickenfoot is built, Firefox will run automatically with Chickenfoot installed and ready to use.
To just run LAPIS by itself (outside of Chickenfoot/Firefox), find the class lapis/src/lapis/Main.java and Run it.
