Development of EulerGUI IDE

TOC

Monitor source changes

If you want to see a log view of the latest changes in source, go to: http://eulergui.svn.sourceforge.net/viewvc/eulergui/?view=log

or, for most frequent modifications :

http://eulergui.svn.sourceforge.net/viewvc/eulergui/trunk/eulergui/?view=log

In command line you can do something like :

svn log | head -30
svn log --revision '{2009-09-01}:{2009-09-25}'
svn log --revision '{2009-09-01}:HEAD'

Yoiu can focus on changes of any file or directory, e.g. here for the documentation:

http://eulergui.svn.sourceforge.net/viewvc/eulergui/trunk/eulergui/html/documentation.html?view=log

There is an automatic mailing list for Subversion commits : subscribe here : eulergui-commits .

Short term tasks for EulerGUI

Watch also here for news and current work: http://eulergui.wiki.sourceforge.net/

Tools for building

You must have installed a Java(TM) 2 Development Kit (JDK), Standard Edition version 1.7 or later, from http://java.sun.com . Of course the Java(TM) 2 Development Kit (JDK) includes a JRE. The tests depend on JDK 1.7, the application only on 1.6 .

On Linux, install these packages: subversion, sun-java7-jdk, maven2, eclipse-jdt, graphviz, vim (vim-x11, vim-gtk, vim-gnome), yap, wget, python, rdflib, hg . For instance on Ubuntu or Debian you can type:

# runtime packages
sudo apt-get install openjdk-7-jre graphviz wget swap-cwm 
# dev tools:
sudo apt-get install subversion subversion-tools openjdk-7-jdk maven2 \
eclipse-jdt vim-gnome jedit yap swi-prolog ia32-libs \
python2.6-dev python-rdflib mercurial \
xserver-xephyr fluxbox

This is in the source in a script named install_packages_ubuntu.sh , that does in fact more .

On Linux, if you don't like to install Sun's Java JDK into your system, you can still download it from java.sun.com, untar it anywhere, set JAVA_HOME variable to this location, and you're all set.

It is now recommended to use Maven 3 (donwload it from Maven site).

Building EulerGUI from sources

To download the latest (trunk) sources from the Subversion repository:

svn co https://eulergui.svn.sourceforge.net/svnroot/eulergui/trunk/eulergui

Maven is used in EulerGUI to build, package and generate eclipse configuration. To install Maven on any platform : http://maven.apache.org/download.html#Installation

As an example, here is what I have for Maven in .zshrc :

export M2_HOME=$HOME/apps/apache-maven-3.0.3
alias mvn=$M2_HOME/bin/mvn
export M2_REPO=$HOME/.m2/repository

alias eg="java -Xmx2G -jar $HOME/.m2/repository/eulergui/eulergui/1.9-SNAPSHOT/eulergui-1.9-SNAPSHOT-jar-with-dependencies.jar $*"
alias protege="( cd $HOME/apps/Protege_4.2; ./run.sh $* )"

Then to build EulerGUI, type in a shell (or in cygwin on Windows)::

cd eulergui/ ; mvn -Dmaven.test.skip=true -f pom_jar.xml install

This will download all the dependencies, as specified in pom.xml, perform all tests, build the executable jar, and put in $HOME/.m2/repository/ . If you are testing several revisions in parallel, you can just do : mvn package ; the executable jar will not be put in the local Maven repository.

Then you can start EulerGUI:

mvn exec:java

which is equivalent to run the jar:

java -jar target/eulergui-1.10-SNAPSHOT-jar-with-dependencies.jar

At any later time, to get the latest changes, type:

svn update

and re-build.


As an alternative to running Subversion and then Maven, there is an all-in-one command to download the POM from the Web, create a local project directory, download the sources, and build , all in one step:

mvn scm:bootstrap  -DconnectionUrl=scm:svn:http://eulergui.svn.sourceforge.net/svnroot/eulergui/trunk/eulergui   -Dgoals=install -Dmaven.test.skip=true 
mv null/target/checkout/ eulergui/ ; rmdir null/target/ ; rmdir null

This way you avoid to install Subversion; Maven takes care of all.

Then afterwards, either you install Subversion for getting the latest changes, or you can use the equivalent Maven command:

mvn scm:update

Anyway, given the standard Maven Build Lifecycle, running any of the targets compile, test, package, or install will first run scm:update .

Convenient scripts

quick_build.sh is a script for building EulerGUI without tests, assuming that all Maven plugins and projects depedencies are already downloaded.

% cat ~/bin/eulergui
java -jar $HOME/.m2/repository/eulergui/eulergui/1.10-SNAPSHOT/eulergui-1.10-SNAPSHOT-jar-with-dependencies.jar $*

% cat ~/bin/eye
java -classpath $HOME/src/eulersharp/2004/01swap/bin/Euler.jar euler.Eye "$@"

% cat /home/jmv/bin/protege
( cd ~/apps/Protege_4 ; ./run.sh $* & )

% % cat ~/bin/n3shell                       
java -Xmx2G -cp  $HOME/.m2/repository/eulergui/eulergui/1.10-SNAPSHOT/eulergui-1.10-SNAPSHOT-jar-with-dependencies.jar \
deductions.runtime.BasicRuntimeShell $*

It's probably even better to use an alias on Unix :

alias eg="java -jar $HOME/.m2/repository/eulergui/eulergui/1.9-SNAPSHOT/eulergui-1.9-SNAPSHOT-jar-with-dependencies.jar"

Getting the classpath

In case you need the classpath for a script or another tool, here is the incantation to show the classpath :

mvn dependency:build-classpath

But that does only output dependencies; to get the full classpath , one needs to add manually the path for EulerGUI itself , e.g. :

$HOME/.m2/repository/eulergui/eulergui/1.9-SNAPSHOT/eulergui-1.9-SNAPSHOT.jar

Troubleshooting

Rarely if you have tests not passing, you should do:

mvn clean

If you want informations about a specific Maven goal, e.g. install, use the goal help:describe :

mvn -Dplugin=install help:describe

Maven's Frequently Asked Technical Questions

Building EulerGUI minimal

EulerGUI minimal has another main class , ProjectGUIMinimal extending the the full EulerGUI one, ProjectGUI.

NOTE: there is currently no special tests for EulerGUI minimal, but since all the difference is in removing buttons in EulerGUI minimal, if the tests pass for full EulerGUI, then the Unit and functionnal tests for EulerGUI minimal are covered .

Running EulerGUI test suite on Windows

See also a more detailed How To install with cygwin (also in french ) .

This has been tested on a machine running Windows 7, with latest JDK 1.6_25 .

There were installed: JDK, Maven 3.0.3, Subversion, Cygwin (facultative).

Then I ran this with the Cygwin shell:

svn co https://eulergui.svn.sourceforge.net/svnroot/eulergui/trunk/eulergui eulergui
export PATH=~/apps/apache-maven-3.0.3/bin:$PATH
export JAVA_HOME="C:/Program Files/Java/jdk1.6.0_25"
export M2_HOME=C:/cygwin/home/Daphné/apps/apache-maven-3.0.3
cd eulergui
mvn install -f pom_jar.xml

According to http://maven.apache.org/scm/subversion.html , it is necessary to create this file :

$user_home/.scm/svn-settings.xml

with (at least) this content:

<svn-settings>
  <configDirectory>C:\Users\<UserName>\AppData\Roaming\Subversion</configDirectory>
</svn-settings>

I installed Subversion from subversion.tigris.org , hence the above configDirectory. Creating svn-settings.xml was not necessary with SlikSvn's distribution of Subversion. It may also work with Cygwin's svn command.

If you don't create this file, you can run svn commands directly from the cmd or Cygwin shell, but with Maven you get this message, ugly and hard to trace in internet :

svn: Can't determine the user's config path

Notes on Scala build

To pave the way for Scala Maven build in the other directory ../eulerscala, pom.xml is now a parent POM, and pom_jar.xml inherents from pom.xml .

pom_jar.xml must be used to actually build the current ( full Java ) EulerGUI .

This also paves the way for splitting EulerGUI into several Maven projects:

eulergui_core -> eulergui_api -> eulergui
eulergui_core -> eulergui_eye -> eulergui_minimal -> eulergui

The Scala+Java build is in this depot :

https://eulergui.svn.sourceforge.net/svnroot/eulergui/trunk/eulerscala

Currently (2012-11-06) there is a copy of an old EulerGUI code base, but it builds and runs.

There will be a new pom.xml that inherits from eulergui project's pom.xml , and the duplicate code will be removed.

Also pom_minimal.xml for eulergui_minimal will inherit from eulergui project's pom.xml, with exclusions for Drools, etc .

When we will switch to Scala build, the above depot trunk/eulerscala will be abandonned, and depot trunk/eulergui will hold the Scala build, plus the sub-projects listed above.

Create an eclipse project

You need to complete "Building from sources" above first.

To create the eclipse configuration for the project eulergui:

mvn eclipse:eclipse -Declipse.downloadSources=true

downloadSources is for downloading sources of the projects EulerGUI depends on. Then before creating a new eclipse project based on the eulergui directory, run this:

mvn -Declipse.workspace=/path/to/my/eclipse/workspace eclipse:configure-workspace

On Linux or cygwin just paste this:

mvn -Declipse.workspace=$HOME/workspace eclipse:configure-workspace

This will create in eclipse the M2_REPO classpath variable, with the value:

<HOME_DIRECTORY>/.m2/repository

Where <HOME_DIRECTORY> stands for your home directory.

In eclipse Preferences, in "Installed JRE's", add the Sun Java 6 JRE (Java Runtime Environment); in Linux Ubuntu it is here:

/usr/lib/jvm/java-6-sun

and check it it as the default one.

Then you can create a new eclipse project based on the eulergui/ directory that you downloaded and where you made the mvn commands.

Troubleshooting

You may have a problem with parser4j, because the jar gotten from Maven may be outdated with respect to the latest sources in EulerGUI. In this case, download the parser4j sources:

svn co https://parser4j.svn.sourceforge.net/svnroot/parser4j parser4j 

create an eclipse project in trunk/parser4j/ from the downloaded sources, make eulergui project dependent from parser4j , and remove M2_REPO/**/parser*.jar from the libraries of project eulergui .

Downloading companion projects' sources

svn co https://deductions.svn.sourceforge.net/svnroot/deductions
svn co https://eulersharp.svn.sourceforge.net/svnroot/eulersharp
hg clone https://fuxi.googlecode.com/hg/ fuxi

Dependencies

Checking dependencies

To display the dependency tree with Maven :

mvn dependency:tree

There is an utility telling when some dependencies are updatable, that is, they have newer versions available : display-dependency-updates-mojo .

Just type :

mvn versions:display-dependency-updates

And there is a similar stuff for Maven plugins :

mvn versions:display-plugin-updates

Compiling dependencies and uploading them on the Maven repository

The issue here is that not all EulerGUI dependencies are on Maven central repository. So we do thse projects' job of publishing their stuff the Maven way.

As specified in pom.xml, the Maven repositry for EulerGUI on Sourceforge is here:

http://eulergui.sourceforge.net/maven2

This file has to be created, otherwise your uploads will be rejected (see below) : $HOME/.m2/settings.xml .

If one wants to add jars to EulerGUI, one should first look in the Maven central repository if it is there :

http://repo2.maven.org/maven2/

and then add an entry in pom.xml .

In the recipes below, it is also possible to try something locally without uploading on the remote repository. To do this, use this argument:

-Durl=file:${HOME}/.m2/repository/

Parser4J

Do this to upload on the EulerGUI Maven repository on Sourceforge the latest .jar from the Parser4J Sourceforge project:

cd ${HOME}/src/
svn co https://parser4j.svn.sourceforge.net/svnroot/parser4j/trunk/parser4j/ \
       parser4j
cd parser4j
# create an eclipse project from the parser4j directory; this will compile all
ant -f buildjar.xml
VERSION=trunk
mvn deploy:deploy-file \
    -Durl=sftp://web.sourceforge.net/home/groups/e/eu/eulergui/htdocs/maven2 \
    -DrepositoryId=repository.eulergui.sf.net \
    -Dfile=${HOME}/src/parser4j/trunk/parser4j/dist/${VERSION}/all/parser4j-all-${VERSION}.jar \
    -DgroupId=parser4j \
    -DartifactId=all \
    -Dversion=${VERSION} -Dpackaging=jar

CAUTION, do not forget to change the version string in the pom.xml for Parser4J.

We also did this for Grappa and Gloze, whose jar was not in any public Maven repository. For example with Gloze :

ln -s ~/apps/Jena-2.6.0/ ~/src/Jena-2.5.7
cd ~/src/Gloze-1.01-beta2/
ant -lib /home/jmv/apps/ant-doxygen-src-1.6.1/lib/ant_doxygen.jar jar
VERSION=1.01-beta2
mvn deploy:deploy-file \
    -Durl=sftp://web.sourceforge.net/home/groups/e/eu/eulergui/htdocs/maven2 \
    -DrepositoryId=repository.eulergui.sf.net \
    -Dfile=${HOME}/src/Gloze-${VERSION}/lib/gloze.jar \
    -DgroupId=com.hp.hpl.jena \
    -DartifactId=Gloze \
    -Dversion=${VERSION} -Dpackaging=jar

and for Grappa:

VERSION=1.2
mvn deploy:deploy-file \
    -Durl=sftp://web.sourceforge.net/home/groups/e/eu/eulergui/htdocs/maven2 \
    -DrepositoryId=repository.eulergui.sf.net \
    -Dfile=${HOME}/apps/grappa-1.2.jar \
    -DgroupId=att \
    -DartifactId=grappa \
    -Dversion=${VERSION} -Dpackaging=jar

For eclipse stuff, the jars available on Maven Central depot were outdated. So we did this:

ECLIPSE_HOME=$HOME/apps/eclipse
groupId=org.eclipse.emf; artifactId=ecore; VERSION=2.4.2.v200902171115
mvn deploy:deploy-file \
    -Durl=sftp://web.sourceforge.net/home/groups/e/eu/eulergui/htdocs/maven2 \
    -DrepositoryId=repository.eulergui.sf.net \
    -Dfile=${ECLIPSE_HOME}/plugins/${groupId}.${artifactId}_${VERSION}.jar \
    -DgroupId=${groupId} \
    -DartifactId=${artifactId} \
    -Dversion=${VERSION} -Dpackaging=jar

groupId=org.eclipse.emf.ecore; artifactId=xmi; VERSION=2.4.1.v200902171115
# mvn deploy ...
groupId=org.eclipse.emf; artifactId=common; VERSION=2.4.0.v200902171115
groupId=org.eclipse.uml2; artifactId=common; VERSION=1.4.0.v200805131030
groupId=org.eclipse.uml2; artifactId=uml; VERSION=2.2.2.v200811051031

OWL API (including Turtle writer) ; now on on a Maven depot :) :

VERSION=3.1.0
JAR=${HOME}/src/owlapi-${VERSION}/owlapi-bin.jar
echo "deploy local file $JAR , possibly overriding $VERSION"
mvn deploy:deploy-file \
    -Durl=sftp://web.sourceforge.net/home/groups/e/eu/eulergui/htdocs/maven2 \
    -DrepositoryId=repository.eulergui.sf.net \
    -Dfile=${JAR} \
    -DgroupId=net.sourceforge.owlapi \
    -DartifactId=owlapi \
    -Dversion=${VERSION} -Dpackaging=jar

jEdit

JAR=${HOME}/src/jEdit-4.3.1-modifs/jedit-4.3.1.jar
echo "deploy local file $JAR"
mvn deploy:deploy-file \
    -Durl=sftp://web.sourceforge.net/home/groups/e/eu/eulergui/htdocs/maven2 \
    -DrepositoryId=repository.eulergui.sf.net \
    -Dfile=${JAR} \
    -DgroupId=org.jedit \
    -DartifactId=jedit \
    -Dversion=4.3.1 -Dpackaging=jar

If you want to use the latest Euler in a Maven build, you can update (override) in the local depot the current version with the latest Euler jar:

EULER_VERSION=2010-08-13
EULER_JAR=${HOME}/src/eulersharp/2004/01swap/bin/Euler.jar
echo "deploy locally file $EULER_JAR , overriding $EULER_VERSION"
mvn deploy:deploy-file \
    -Durl=file:${HOME}/.m2/repository/ \
    -Dfile=${EULER_JAR} \
    -DgroupId=euler \
    -DartifactId=euler \
    -Dversion=${EULER_VERSION} -Dpackaging=jar

NxParser ( N-Triples parser )

JAR=${HOME}/src/nxparser-read-only/dist/nxparser-1.2.1.jar
echo "deploy local file $JAR"
mvn deploy:deploy-file \
    -Durl=sftp://web.sourceforge.net/home/groups/e/eu/eulergui/htdocs/maven2 \
    -DrepositoryId=repository.eulergui.sf.net \
    -Dfile=${JAR} \
    -DgroupId=org.semanticweb.yars.nx.parser \
    -DartifactId=NxParser \
    -Dversion=1.2.1 -Dpackaging=jar


The repository Id refers to the following content in $HOME/.m2/settings.xml (and also to an entry in pom.xml) . This file has to be created, otherwise your uploads will be rejected.

<settings>
    <servers>
      <server> <!-- for the Maven depot -->
        <id>repository.eulergui.sf.net</id>
        <username>jmvanel,eulergui</username>
        <password>???</password>
        <filePermissions>775</filePermissions>
        <directoryPermissions>775</directoryPermissions>
      </server>
      <server> <!-- for site:deploy -->
        <id>eulergui.sourceforge.net</id>
        <username>jmvanel,eulergui</username>
        <password>???</password>
      </server>
    </servers>
</settings>

On Windows, this file is to be created :

C:\Documents and Settings\USER_NAME\.m2\settings.xml

This allows to completely automatize the upload.

The same settings are used to deploy EulerGUI itself :

mvn deploy

Making a release

Some background readings:

http://maven.apache.org/guides/mini/guide-releasing.html

http://maven.apache.org/plugins/maven-release-plugin/index.html

http://docs.codehaus.org/display/MAVENUSER/Release+Plugin

http://docs.codehaus.org/display/MAVENUSER/MavenAndSourceforge

http://maven.apache.org/plugins/maven-site-plugin/usage.html

http://svnbook.red-bean.com/nightly/en/svn-book.html#svn.branchmerge.tags

The shell variable REL stands for the release number, for example 1.10 .

First, instead of making a release, you can Upload a snapshot (your settings.xml should be OK, see above) .

Finally, the generated Maven Web site (for humans) is here : http://eulergui.sourceforge.net/maven-site/

Uploading a snapshot

In another shell:

ssh -t jmvanel,eulergui@shell.sourceforge.net create

then :

mvn -Dmaven.test.skip=true deploy

There is a script doing all this:

deploy_snapshot.sh

Tests for developpers

IMPORTANT: we care about tests, and for the Subversion trunk the test suite should always pass at any time.

You must have installed a Java(TM) 2 Development Kit (JDK), Standard Edition version 1.7 or later, from http://java.sun.com . Of course the Java(TM) 2 Development Kit (JDK) includes a JRE. The tests depend on JDK 1.7, the application only on 1.6 .

To run the tests through Maven, that collects all JUnit tests, type :

LANG=en mvn test

or, for an HTMl report in target/site/surefire-report.html :

LANG=en mvn surefire-report:report

All these tests should pass at any time. If you want to add a test before implementing or fixing a bug (which is a good thing !), please name it pendingtestXXX() ; so it will not be run by JUnit, but still be recorded in the code SCM.

During development, you may run a single test class repeatedly. To run this through Maven, set the test property to a specific test case, e.g.:

LANG=en mvn -Dtest=n3_project.TestReasonning --errors test

Due to internationalization, we need to set the language to English for the tests. On windows it is:

set lang=en
mvn test

Locating a bug with svn-bisect

svn-bisect does dichotomic search of a bug.

http://manpages.ubuntu.com/manpages/lucid/man1/svn-bisect.1.html

Here is an example of a real session :

sudo apt-get install subversion-tools

svn update -r 3077
 ./start_embedded_X_server.sh
# this succeeds:
DISPLAY=:1 LANG=en mvn --offline -Dtest=BasicRuntimeTest test
# then one can intialize bisect:
svn-bisect start 3077 3129
svn-bisect run 'DISPLAY=:1 LANG=en mvn --offline -Dtest=BasicRuntimeTest test'...
Regression found!
Last good revision: r3124
First bad revision:
------------------------------------------------------------------------
r3125 | jmvanel | 2012-06-25 22:57:51 +0200 (lun. 25 juin 2012) | 4 lignes
- Drools/N3 engine: now static method calls work outside of rules
- examples/table_app.n3p now works
TODO: now BasicRuntimeTest.testJavaMappingConsequentNewVariable() fails

svn-bisect reset

Tests : CAUTION - TROUBLESHOOTING

Accelerate tests

If you're in a hurry, type this, which will avoid searching for Maven plugin updates, and reading from the Internet all the POM for project dependencies :

LANG=en mvn --no-plugin-updates --offline test

We can now bypass the Parser4J tests, since the Parser4J N3 parser in EulerGUI is quite stable now. To bypass Parser4J tests, just run the tests like this:

LANG=en mvn -DPARSER4J_TESTS=no test

Of course, you can combine both:

LANG=en mvn -DPARSER4J_TESTS=no \
    --no-plugin-updates --offline test

And if you're in a BIG hurry (but that's not recommended) you can skip tests with :

-Dmaven.test.skip=true 

GUI functional tests

We had Abbot GUI tests (Abbot is a framework for testing Java GUI's); but after months of

developments, it was too difficult to update the tests.

So we switched to Jemmy; the tests are written in Java, and added to the JUnit tests. Test inheriting from TestJemmy include the use cases from the Déductions project Manual: generate application from URL sources in N3, OWL, RDFS, UML, and eCore languages. We will add more Jemmy tests in this directory :

eulergui/src/test/java/eulergui/gui/

To use local versions of the Déductions projects, add this to the Maven command:

-DargLine="-DDEDUCTIONS_PROJECTS=local"

Visualize the Swing component tree

To visualize the Swing component tree in all windows, uncomment this line in class DroolsInferenceEngine:

ComponentTree.showAllWindows();

and run Drools inference.

Abbot is also useful to visualize the Swing components tree. The recipe for that is here:

  1. download and install Abbot
  2. add the Abbot jars to your eclipse project , or create an eclipse project and make the eulergui project dependent of the Abbot project (the latter seems quicker)
  3. run class
    abbot.editor.Costello

    with argument

    src/test/abbot/test_person_abbot.xml
  4. click on execute in the Abbot window's upper right corner; this will replay the recorded user actions , and GUI assertions.

Deactivate the windows in Jemmy tests

You would like to deactivate the windows produced by Jemmy altogether. Indeed it is difficult to work on the computer while the tests are running, because the mouse is manipulated.

If you are on Linux, you can start a second X server... Here's the script used to start the embedded X server Xephyr (thanks to Peter Arrenbrecht) . Note that you need a window manager for the new X server. Fluxbox is used here, which is fairly lightweight. You need to pass the environment setting DISPLAY=:1 to tests that should run on this X server. For example:

LANG=en DISPLAY=:1 mvn test

Here's the script; it is in the Subversion depot as start_embedded_X_server.sh :

#! /bin/bash
# Xnest -ac :1 -geometry 1280x1024 &
Xephyr -ac -screen 1280x1024 -br -reset -terminate :1 &
sleep 1s
fluxbox -display :1 &
echo "Start your apps with DISPLAY=:1 ..."

So, all together, the efficient way to run the tests is :

./start_embedded_X_server.sh
LANG=en DISPLAY=:1 mvn -DPARSER4J_TESTS=no \
    --no-plugin-updates --offline test

The last command is actually in the repository as quick_tests.sh .

Debug

To debug the Project class, there are several JUnit tests in src/test/java/n3_project.

To debug the generated GUI, you can use Tools / show Component Tree .

There is a separate how-to page to debug an N3 rules set.

Drools stuff

To see the Java classes generated by the Drools compiler, in class N3SourcetoDrools you can set field keep_drools_java_generated to true; then the Java generated by Drools will be in directory /tmp/drools .

To generate a trace of N3 rule firings by intrumenting the N3 to Drools translation, set boolean trace_switch_on in class DroolsTripleHandler .

To debug insertions, retractions, and updates to the Drools level, use a DebugWorkingMemoryEventListener :

ksession.addEventListener( new DebugWorkingMemoryEventListener() );

Maven

To debug a Maven run, or running EulerGUI from the jar, use the "Remote Java debug" in eclipse . Start EulerGUI like this:

java -Djava.compiler=NONE -Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket,server=y,address=8000 \
     -jar target/eulergui-1.11-SNAPSHOT-jar-with-dependencies.jar

Then create and launch a debug configuration in eclipse, with "Attach socket" activated.