Requirements

To use this software you need to install first a Java jre (at least version 5) and Java3d (at least version 1.5.0).

This release was developed on Windows, its look and behavior may vary on other platforms. In case of trouble, please contact me with the email provided on "Contact" page.

Configuration

To ease use, projects parsed with Relief are described in a configuration file.

This file is written in standard XML, we will use project.xml as an example:

<parser name="JavaParser">
  <driver>org.workingfrog.relief.plugins.java.JavaConfigHandler
  <projects default="myProjectName">
    <project name="myProjectName">
      <jrePath jreVersion="1.4">C:\Program Files\Java\j2re1.4.2_06</jrePath>
      <basedir>C:\path\to\my\project\base\directory</basedir>
      <blackbox />
      <build>bin</build>
      <src>
        <path>src</path>
        <path>test</path>
      </src>
      <lib show="false">
        <path>myFirstLibrary.jar</path>
        <fullpath>C:\full\path\to\anOtherLibrary.jar</fullpath>
      </lib>
    </project>
    <project name="anOtherProjectName">
      <jrePath jreVersion="1.6">C:\Program Files\Java\jdk1.6.0_01\jre</jrePath>
      <basedir>C:\path\to\my\other\project\base\directory</basedir>
      <build>bin</build>
      <src>src</src>
      <lib>
        <path>oneLibrary.jar</path>
      </lib>
    </project>
  </projects>
</parser>

Tags parser and driver are mandatory and must not be edited.

Attribute default in tag projects specifies which project to parse if no one is mentioned on the command line.

Tag jrePath specifies the java runtime used by the project. If a jdk is used, path must end with it's "jre" directory, see the two examples above. Attribute jreVersion is "1.3", "1.4", "1.5", "5", "1.6" or "6": it is the source code version.

blackbox determines the way the project will be parsed (focus on API or implementation ?). If no source files directories are provided blackbox is automatically checked.

Tag basedir is the root directory of one project.

build refers to root directory where compiled versions of your java source files are generated.

src to root directory of your java sources files.

Finally with lib you define what libraries your project relies upon. The optional attribute show has value "true" (default) or "false" ; it controls display of dependencies to Java core classes and libraries.

path tags in build, src and lib are subdirectories of basedir. If ressources are located outside your project directory use fullpath tag.

Usage

Open a console and go in Relief directory.
Type java -jar relief.jar [path/to/my/configurationFile.xml [project name to load]].

If you don't provide any argument to Relief or start it by double clicking its icon, Relief expects to find a configuration file named "projects.xml" in the directory where you launched it.

For example, typing java -jar relief.jar project.xml with the file described above will parse myProjectName while java -jar relief.jar project.xml anOtherProjectName will load anOtherProjectName.

If a default project is defined but you want to choose an other one, use an undefined project name, like choose for example: java -jar relief.jar project.xml choose, this way Relief will pop up a window allowing to choose a project defined in the configuration file.

Troubleshooting

If you get an error message on the console like this one:

Exception in thread "Main Thread" java.lang.NoClassDefFoundError: javax/media/j3
d/SceneGraphObject at org.workingfrog.relief.Relief.main(Relief.java:60)

It means either java3d is not installed or you have many java jre installed and are using one without java3d.

The java compiler used to parse source files may output warnings. They may help you find missing libraries or build paths in configuration file. They will also diagnose bad java version ("java version < 5.0" checkbox).

Some java3d exceptions may be thrown when using the view. It seems to be minor ones as the view is still usable but I could'nt figure yet their cause. Any feedback is welcome.