Build and Test frysk From Source

Build and Test FAQ
Eclipse FAQ
GIT FAQ

Fedora
Ubuntu
RHEL
Debian

This page provides guidelines for building frysk, checked out from Git, on a number of systems.

Set up your system's build environment

First you will need to set up your system's build environment so that all its prerequisites are met.

You will need to install the following:

sudo yum install -y \
    antlr jdom junit gcc-java gcc-c++ \
    libglade-java-devel libvte-java-devel \
    automake xmlto transfig eclipse-ecj dogtail \
    sharutils git audit-libs-devel binutils-devel \
    yelp libtool make rpm-build

In addition, you may need to force a re-install of java-1.5.0-gcj. See Fedora Bug 377341 for details.
For additional updates, check the Fedora 9, tracker bug.
For earlier Fedora releases check the Fedora Page

RHEL 5.1

You will need to install the following:

sudo yum install -y \
    antlr jdom junit gcc-java gcc-c++ \
    libglade-java-devel libvte-java-devel \
    automake xmlto transfig eclipse-ecj dogtail \
    sharutils git audit-libs-devel binutils-devel \
    yelp libtool make

For additional updates, RHEL 5 tracker bug.
For earlier RHEL releases check the RHEL Page.

Ubuntu (Gutsy Gibbon) Debian

You will need to install the following packages:

g++ binutils-dev make gcj java-gcj-compat-dev \
libglade-java-dev libvte-java-dev antlr libjdom1-java \
automake libtool pkg-config autotools-dev libaudit-dev \
sharutils transfig libxml2-utils xmlto gs-gpl yelp

For additional updates, check the Debian or Ubuntu tracker bug.
For earlier Ubuntu releases check the Ubuntu Page.

Check out frysk from Git

Normally you would use:

$ git-clone git://sourceware.org/git/frysk.git

If you have Git write access to the Frysk repository then:

$ git-clone ssh://sourceware.org/git/frysk.git

Configure

On X86 or X86_64.

$ ( mkdir build && cd build && ../frysk/autogen.sh )

On a 32-bit-default 64-bit system, such as the PPC64, a 64-bit build environment needs to be passed to autoconf's configure as command line arguments, letting configure save them as part of the configuration process. This is done by specifying them on autogen.sh's command line, vis:

$ ( mkdir build && cd build && ../frysk/autogen.sh \
  PKG_CONFIG_PATH=/usr/lib64/pkgconfig \
  CC='gcc -m64 -mminimal-toc' \
  GCJ='gcj -m64 -mminimal-toc' \
  GCJLINK='gcj -m64 -mminimal-toc' \
  CXX='g++ -m64 -mminimal-toc' )

Verify the build environment (optional)

Both the frysk-imports and frysk-gtk directories include tests to ensure that the build system (compiler, kernel, and libraries) are working correctly. Any FAILing tests should be investigated (XFAIL and XPASS tests are OK).

$ ( cd build/frysk-imports/tests && make check )
$ ( cd build/frysk-gtk/tests && make check )

Build

$ ( cd build && make -j2 )

Test

On Fedora Core 5, there should be no failures.

$ ( cd build && make check )

Run

frysk can then either be run from the build tree ...

$ ./build/frysk-gui/frysk/gui/FryskGui

... or installed and run from there

$ ( cd build && sudo make install )
$ frysk

Developer Questions, such as building and testing frysk, and using `GIT`; with answers

Building and Testing Questions

How do I add, rename, or delete a Java file?

Add, rename, or delete the file.
Run ./bootstrap.sh

How do I add a Java program that should be installed into bin/?

in the frysk/pkgbindir/ directory, create .java and .xml files named to match the installed binary
run ./bootstrap.sh

For instance, the files frysk/pkgbindir/ftrace.java and frysk/pkgbindir/ftrace.xml are installed into bin/ and share/man/ respectively.

How do I add a JUnit test-case?

Following the JUnit convention:

create the test file named TestBLAH.java
add a test method with signature public void testBLAH () for each test
run ./bootstrap.sh

Why do JUnit test-cases live in the same directory as the code?

The JUnit documentation may discuss this, but anyway:

so that the test is in the same package as the code being tested giving fuller access to the packages methods and classes
so that the tests are not missed or burried in a completly separate source tree

How do I do blah blah blah with TestRunner or funit?

The command line options accepted by installed program funit, and described in funit's man page, are also accepted by the build-tree program TestRunner. For instance:

 TestRunner -console frysk=FINEST frysk.proc.TestClass

runs just the tests from frysk.proc.TestClass with trace logging written to the screen.

Also

 TestRunner frysk.proc.TestClass.testName

and

 TestRunner testName(frysk.proc.TestClass)

will both run specific tests.

How do I refer to an external executable or data file in a test?

Use:

frysk.junit.Paths.getExecPrefix(): Which will refer to either the installed lib{,64}/frysk/ or build tree frysk/pkglibdir
frysk.junit.Paths.getDataPrefix(): Which will refer to either the installed share/frysk/ or build tree frysk/pkgdatadir

The tesets in the frysk-imports/tests/ and frysk-gtk/tests/ directories exercise bugs in components such as the kernel, GCJ and CLASSPATH, and Java-GNOME, and not frysk. Why?

Risk Management.
To ensure onging stability in the complex and emerging technologies on which frysk depends, the frysk build tree retains locally regression tests for bugs reported against those components.

Are both gcj and ecj required when building frysk? If so, why, or why not?

A frysk build only requires and always uses gcj when compiling Java code.
In addition, to maintaining a high level of code quality, and ensure that the gcj is only presented with correct Java source, frysk's build system lints its Java code base using ecj when that compiler is also available.
Note that frysk's build system does not use ecj as the build compiler as that would result in a non-deterministic build - one that changes dependant on the presence or absence of ecj.

How do I write accessible code that can be seen by dogtail?

See this link: accessible tutorial

Why are @libdir@ and @pkglibdir@ not permitted in man-pages?

Because the path is not identical across 32-bit (e.g., /usr/lib/frysk) and 64-bit (e.g., /usr/lib64/frysk) systems. Instead manual pages explicitly refer to @pkglib32dir@ and/or @pkglib64dir@.

Using valgrind to debug frysk

Rick writes.
As mentioned in our meeting today, valgrind can be used to help debug gcj-compiled code, but it helps if a "suppression file" is pointed to when activated to help filter out errors that are expected due to some garbage collection tricks. Tom Tromey wrote an article on using valgrind and is located here. In this article, Tom points out this website which has some useful information. And this website in turn points top a website that has the "suppression file" that should be used with valgrind. If the suppression file is not used, the output from valgrind when used on gcj-generated code is several times larger and contains useless information.***NOTE*** The suppression file in the last link assumes libgcj.so.6.0.0 is being used. If that file is to be used with the current version of libgcj all occurrences of "libgcj.so.6.0.0" must be changed to "libgcj.so.7.0.0" or else no suppression will take place.

Eclipse Questions, with Answers

How do I "import" frysk into eclipse?

First you will need to check out and build frysk from the command line; this will create the directory build/eclipse which contains pre-configured eclipse .project and .classpath files.
Once the build has finished, from eclipse:

Select: File -> Import ...; to bring up the Import window
Select: General + Existing Project Into Workspace; and click next
Fill in: Select root directory; with the path to the build/eclipse directory.
Click: Finish

How do I use gcj? (aka, I see an error about gnu.gcj.RawData)

Since frysk relies on some gcj specific implementation details (cni and gnu.gcj.RawData) you want to make sure to have the gcj JRE/JDK compat package install (java-1.5.0-gcj-devel). To make sure this JRE/JVM is used in the Frysk Eclipse workspace do:

Expand 'my project' in the package browser.
Select JRE System Library.
Right click and select Configure...
Select Alternate JRE.
Click Installed JREs...
Click Add...
Add JRE home directory: /usr/lib/jvm/java-1.5.0-gcj.
Make sure this JRE is now selected before clicking finish.

The project should now auto-re-build without any errors.

What should my eclipse format options be set to?

frysk pretty much follows the standard Java Conventions; to set this locally:

Select: Window -> Preferences; to bring up the Preferences window
Select: Java + Code Style + Formater
Set Active Profile to Java Conventions

What should the eclipse compiler be set to?

fryskUses Java 1.4.2; to select that compiler; to set this globally:

Select: Window -> Preferences; to bring up the Preferences window
Select: Java + Compiler
Set the Compiler Compliance Level to 1.4
Check that the Default Compliance Settings are used.

What eclipse packages are recommended?

Check for at least the following (on Fedora 8):

sudo yum install eclipse eclipse-changelog \
    eclipse-cdt eclipse-jdt \
    java-1.4.2-gcj-compat-src

and don't forget to configure the Eclipse ChangeLog Plug-in; see: Window -> preferences; ChangeLog; and set your e-mail address.

How do I build frysk from eclipse?

Use CNTRL-B.

GIT Questions, with Answers

See our Git page for examples of working with Git.

How do I cut a branch?

See our Git page's section on branches. A good Git practice is to take advantage of the hierarchical nature of branch names and give short-lived "topic" branches names like topic/regsbugfix.

How do I import a third party package into frysk-imports?

Checkout a branch for the imported package only. Future updates to the package will be made on this branch. You do this by checking out the first revision of Frysk, which was empty, then add and commit the frysk-imports directory and the package. After that you checkout the Frysk master branch and merge in the branch with the packge.

Example:

$ git-checkout -b vendor/LIBFOO genesis(1)
$ mkdir frysk-imports
$ tar xf libfoo.tar -C frysk-imports
$ git-add frysk-imports(2)
$ git-commit -m"Initial import of libfoo"
$ git-checkout master(3)
$ git-merge vendor/LIBFOO(4)
$ git-push origin master vendor/LIBFOO:vendor/LIBFOO(5)

Checkout the first revision of Frysk, which we've tagged with the tag genesis. with the -b flag we create a new branch for the checkout. All our 3rd party import branches have a prefix of vendor/ and then the name of the package in uppercase.
Adding a directory recursively adds its contents.
Switch back to the master branch
The merge creates libfoo and its contents on the master branch.
Push the imported changes to the master branch in the remote repository,and also create a new remote branch for the import in the remote repo.

How do I update a third party package in frysk-imports?

This assumes that there is already a vendor branch in git for the package under frysk-imports.

libunwind is used as an example.

This is an example of importing a new libunwind version from upstream
by putting it on the frysk vendor branch in git and then merging it
to trunk.


 Get the libunwind vendor branch. 

     $  git-branch vendor/LIBUNWIND origin/vendor/LIBUNWIND && git-checkout vendor/LIBUNWIND
 Remove old stuff that needs to be replaced. 

     $ rm -rf frysk-imports/libunwind 
 Get upstream stuff and put it in
     (make sure you don't accidentially copy over the upstream .git dir) 

     $ cp -r ~/upstream/libunwind frysk-imports/ && rm -rf frysk-imports/libunwind/.git 
 Make sure all new files are added 

     $ git add frysk-imports/libunwind 
 Commit (use a commit messsage like "Import of libunwind version
     libunwind-20071122") and push 

     $ git-commit -a && git-push origin vendor/LIBUNWIND:vendor/LIBUNWIND 


The vendor branch is now updated, now we merge the result to the trunk.


 Switch to trunk 

     $ git-checkout master
 Merge new vendor branch to the trunk 

     $ git-merge vendor/LIBUNWIND
 Resolve the conflicts using git-rm for files not needed,
     editing files with conflict markers and git-add each one
     after resolving the issues (if you fix a file more than once, you
     have to git-add it after each change. Keep an eye on
     git-status to spot any modified, but not added changes).
 Do a full clean build and double check the test results. 

     [.. lots of time passes...]
 Double check your patches (all should now be staged in the git index)
     with 

     git-diff --cached
 Commit and push the result (git will have generated a merge message
     for you already that you can use in the commit). 

     $ git-commit && git-push 

     If the push fails because other commits have been done DON'T
     try to rebase, this will horribly fail!. Use git-merge 

     $ git-fetch origin && git-merge origin 

     Double check the merge went OK and only then git-push.


If too much time has passed since the start the push will fail because
someone else will have pushed something already. Trying to do
a git fetch origin; git rebase origin seem to fail, so
you have to just do a git pull &&; git push then (which
creates an extra merge message, but that seems just fine).

Comments on how to improve this process appreciated.



How do I create a tag or a branch at a certain date?
There isn't a direct command for doing this in Git. Instead, you
can find the SHA1 hash of the last commit prior to date with a command
like:
git rev-list --before=2008-01-14 --pretty=oneline -n1 HEAD

and make the branch or tag using the hash.


How do I create a release snapshot?
This creates a snapshot from midnight last night (GMT):
date=`date -u +"%Y.%m.%d"`
echo date=$date 1>&2
shar1=`git-rev-list --before=$date -n1 HEAD`
echo shar1=$shar1 1>&2
version=`cat common/version.in | sed \
  -e 's/\.[Y0-9][Y0-9][Y0-9][Y0-9]\.[M0-9][M0-9]\.[D0-9][D0-9]$/.'$date'/'`
echo version=$version 1>&2
rm -rf frysk-$version
git archive --prefix=frysk-$version/ $shar1 | tar xpf -
echo $version > frysk-$version/common/version.in
tar cfj frysk-$version.tar.bz2 frysk-$version