| Home | Wiki | Use Cases | Work Flows | FAQ | Get Involved | Bugzilla | Build | Blog | Documentation

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

Fedora 8
  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

  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 8, tracker bug.
  For earlier Fedora releases check the Fedora Page</a. </dd>
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)

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

  2. Adding a directory recursively adds its contents.

  3. Switch back to the master branch

  4. The merge creates `libfoo` and its contents on the master branch.

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