use JDT again

[eclipsethinslicer.git] / Svelte / HACKING.txt

HOW TO INSTALL SOURCE
For more detailed beginners' instructions for Windows, see HOWTOINSTALLSOURCE.txt

Currently the Slicer source code is kept in a git repository. Git is a powerful distributed version control system. In contrast to traditional systems like CVS and SVN, each user has a complete repository f the code with full history. You can make local branches and commits, easily keeping upstream and personal versions separate. With git-based development, there does not have to be a central SVN-style repository; however, in this case we use the git repository at repo.or.cz as the central/canonical repository.

The source code needed to work on the slicer comes from three different repositories on repo.or.cz:

wala -- contains WALA source code from trunk/ on SVN. The three branches currently hosted on repo.or.cz are:
        * master -- strict trunk. This has to be updated manually with git-svn so is out of date probably.
        * v1.1.2 -- unmodified v1.1.2
        * v1.1.2-LOCALBUGFIXES -- WALA v1.1.2 with some local bugfixes necessary to make Polyglot-based slicer work.
        * v1.1.2-jdt -- WALA v1.1.2 with above-mentioned bugfixes but also lots of work done on a JDT to CAst translation. Most JDT work is in package com.ibm.wala.cast.java.translator.jdt.

walaincubator -- contains WALA source code from the incubator/ directory on SVN. Original WALA source code, no changes needed for the slicer. branch v1.1.2 is closest SVN revision to WALA v1.1.2, and is used for the slicer.

eclipsethinslicer -- master is the only interesting branch, the others are outdated. Built on wala v1.1.2-jdt and walaincubator v1.1.2.

To clone these repositories, run the following commands:

git clone git://repo.or.cz/wala.git
git clone git://repo.or.cz/walaincubator.git
git clone git://repo.or.cz/eclipsethinslicer.git

If you have write access you can instead clone each repository with a command like:

git clone git+ssh://myusername@repo.or.cz/srv/git/eclipsethinslicer.git 

After you download all three repositories you will have the three directories which contain Eclipse project directories inside them. In Eclipse, you can start a new workspace and then import these projects into it without moving them. This way, you can use still git to manage your source code.

CREATING TRACKING BRANCHES
To access the other branches on the remote repositories you must create what git calls "tracking branches". Tracking branches are local branches which are directly linked to the remote branches.

In the wala repository, you at least want to get the branch used for the slicer (which contains the JDT front-end) and check it out:

git branch --track v1.1.2-jdt origin/v1.1.2-jdt
git checkout v1.1.2-jdt

The second line switches to new the branch, so that all the files in the working directory will be updated to that branch.

In walaincubator you will want to create a v1.1.2 branch and switch to it:

git branch --track v1.1.2 origin/v1.1.2
git checkout v1.1.2

In eclipsethinslicer the master (default) repository is fine.

For more git commands see the git man pages and the tutorials at http://git.or.cz/. Here are the basics:
To update your local repository from the server, run "git pull".
To push changes to the server, run "git push" for master, or "git push origin BRANCHNAME" for a specific branch branchname.
You can make branches with the command "git branch <branchname>".
The git configuration file is .git/config in each repository directory. This contains information about remote branches that is sometimes useful. For instance, if you want "git push" to push all branches, you can add a line under [remote "origin"]. For example, this section in my .git/config file looks like:
[remote "origin"]
        url = git+ssh://elb@repo.or.cz/srv/git/wala.git
        fetch = +refs/heads/*:refs/remotes/origin/*
        push=master:refs/heads/master
        push=v1.1.2-jdt:refs/heads/v1.1.2-jdt
        push=v1.1.2:refs/heads/v1.1.2
        push=v1.1.2-LOCALBUGFIXES:refs/heads/v1.1.2-LOCALBUGFIXES


REMOTE BRANCHES:
Let's say you have a branch called CURRENTBRANCH and want to make a new remote branch for this, named NEWREMOTEBRANCH:
git push origin CURRENTBRANCH:refs/heads/NEWREMOTEBRANCH
git fetch origin
git branch --track NEWREMOTEBRANCH origin/NEWREMOTEBRANCH

You can delete it by these commands:
git push origin :refs/heads/NEWREMOTEBRANCH
git branch -d NEWREMOTEBRANCH

GIT-SVN
The wala and walaincubator git repositories are updated from svn with a command called git-svn. git-svn establishes a two-way link between a local git repository and a remote svn repository by allowing you to:
1) fetch SVN revisions as git commits and update/rebase a local branch
2) push git commits to a local branch back to SVN as a series of SVN commits
For the slicer, git-svn is used to fetch the latest version of WALA from SVN. The latest version is downloaded into the master git branch, which should be kept as a pure branch from SVN. If you want to make a modified WALA based on the current SVN, you can create more branches starting from master.

To use git-svn to get the latest wala from SVN, follow these steps:
1) make sure you have a cloned wala repository cloned that has an unmodified "master" branch (i.e., the last commit in the "master" branch came from WALA SVN)
2) add the following to the end of your .git/config file in the wala repository:
[svn-remote "svn"]
        url = https://wala.svn.sourceforge.net/svnroot/wala/trunk
        fetch = :refs/remotes/git-svn
3) tell git that master came from SVN by copying the ref file:
cp .git/refs/remotes/origin/master .git/refs/remotes/git-svn
4) run "git-svn fetch" and "git-svn rebase"
Your "master" branch should then be up to date with WALA SVN and you can update if from then on just by running "git-svn rebase". You can push the update to the git repository with "git push"

To do the following for walaincubator, follow the above steps, except in step 2, the url should reference incubator:
[svn-remote "svn"]
        url = https://wala.svn.sourceforge.net/svnroot/wala/incubator
        fetch = :refs/remotes/git-svn