ConfiguringAntBuildFiles

From Protege Wiki
Revision as of 07:29, June 17, 2011 by Tredmond (talk | contribs) (How the Protege ant scripts work: (checkpoint save))

Jump to: navigation, search

Using and Configuring Protege Ant Build Scripts

There is a standard format for the protege ant build scripts. The main idea behind these build scripts is that most of the dependencies needed by a plugin project can be found inside a protege distribution. Therefore the build file uses the PROTEGE_HOME environment variable to point to a Protege distribution and find the dependencies from there. This removes the problems where users commit jar files from the protege distribution and have to keep updating them.

So the simplest way of configuring the invocation of an ant build script is to set the PROTEGE_HOME environment variable. The way that this is done is system dependent:

  • On unix systems from the command line use "export PROTEGE_HOME=/home/tredmond/Desktop/Protege". This command can also be put in a .bashrc file. On the command line, unix systems also allow one to set a property for the duration of one command as follows
                    PROTEGE_HOME= /home/tredmond/Desktop/Protege" ant install
  • OS x machines are unix machines so all the unix techniques apply. However, in addition to this there is the
                 ~/.MacOSX/environment.plist

    file which contains a set of properties. The advantage of using this file is that it is invoked before applications that are invoked with a double click. There is a nice page about this here. So it might make sense to put environment property values in here that are seen by an IDE which is started with a double click.
  • On windows systems, right click on MyComputer and select settings. Then find Environment Variables and click then locate PROTEGE_HOME, press edit and change to the path to protege.
  • In eclipse follows these directions and then go to the environment settings page and add the environment setting.

In addition to the above, any variable in a Protege ant script can be configured by setting the value in a local.properties file. This is useful for an installation into a non-Protege application such as a tomcat web server.

Finally, for developers making install scripts, the ant target allows the developer to set variables in the called ant script as parameters. So for instance the place to install protege can be set in the ant script as follows:

        <ant antfile="...">
            <property name="protege.home" location="./build/Protege_4.0_NCI"/>
            ...

This is a very flexible technique and can be used to override any variables in the called ant script. This type of technique is being used at NCI to create custom builds of the NCI Protege in a controlled and consistent fashion.

How the Protege ant scripts work

The philosophy of the Protege build scripts is to use the PROTEGE_HOME environment variable as a pointer to the Protege installation directory and as a repository of the latest jars. We will show how this works by demonstrating how to quickly build a Protege 3 installation containing a few basic plugins. This page uses Protege 3 examples but the Protege 4.1 build files work in exactly the same way (except that in that case PROTEGE_HOME must point to a Protege 4.1 installation directory rather than a Protege 3 installation directory).

We will start by creating an empty directory and installing the core Protege 3 implementation into that directory. Please note that this build script was run on a very slow machine and will run much faster on modern platforms.


[tredmond@Andromeda protege-core]$ mkdir /tmp/Protege3
[tredmond@Andromeda protege-core]$ export PROTEGE_HOME=/tmp/Protege3
[tredmond@Andromeda protege-core]$ svn info
Path: .
URL: http://smi-protege/repos/protege/protege-core/trunk
Repository Root: http://smi-protege/repos/protege
Repository UUID: 30a32298-b1ee-0310-87e3-a7336bc3aa68
Revision: 14650
Node Kind: directory
Schedule: normal
Last Changed Author: tredmond
Last Changed Rev: 14624
Last Changed Date: 2009-06-27 11:29:11 -0700 (Sat, 27 Jun 2009)

[tredmond@Andromeda protege-core]$ ant clean
Buildfile: build.xml

clean-clips:

clean:

BUILD SUCCESSFUL
Total time: 1 second
[tredmond@Andromeda protege-core]$ ant install
Buildfile: build.xml

init:

prepare:
    [mkdir] Created dir: /Andromeda/Users/tredmond/dev/workspaces/protege3/protege-core/classes
    [mkdir] Created dir: /Andromeda/Users/tredmond/dev/workspaces/protege3/protege-core/classes.junit
    [mkdir] Created dir: /Andromeda/Users/tredmond/dev/workspaces/protege3/protege-core/dist
    [mkdir] Created dir: /Andromeda/Users/tredmond/dev/workspaces/protege3/protege-core/docs/apidocs

check-clips:

maybe-clean-clips:

clean-clips:

javacc:
   [javacc] Java Compiler Compiler Version 4.0 (Parser Generator)
   [javacc] (type "javacc" with no arguments for help)
   [javacc] Reading from file /Andromeda/Users/tredmond/dev/workspaces/protege3/protege-core/bin/Parser.jj . . .
   [javacc] Warning: Line 4, Column 5: Bad option name "OPTIMIZE_TOKEN_MANAGER".  Option setting will be ignored.
   [javacc] Note: UNICODE_INPUT option is specified. Please make sure you create the parser/lexer using a Reader with the correct character encoding.
   [javacc] File "TokenMgrError.java" does not exist.  Will create one.
   [javacc] File "ParseException.java" does not exist.  Will create one.
   [javacc] File "Token.java" does not exist.  Will create one.
   [javacc] File "SimpleCharStream.java" does not exist.  Will create one.
   [javacc] Parser generated with 0 errors and 1 warnings.

compile:
    [javac] Compiling 891 source files to /Andromeda/Users/tredmond/dev/workspaces/protege3/protege-core/classes
    [javac] Note: Some input files use or override a deprecated API.
    [javac] Note: Recompile with -Xlint:deprecation for details.
    [javac] Note: Some input files use unchecked or unsafe operations.
    [javac] Note: Recompile with -Xlint:unchecked for details.
     [rmic] RMI Compiling 1 class to /Andromeda/Users/tredmond/dev/workspaces/protege3/protege-core/classes
     [rmic] RMI Compiling 1 class to /Andromeda/Users/tredmond/dev/workspaces/protege3/protege-core/classes
     [rmic] RMI Compiling 1 class to /Andromeda/Users/tredmond/dev/workspaces/protege3/protege-core/classes
     [rmic] RMI Compiling 1 class to /Andromeda/Users/tredmond/dev/workspaces/protege3/protege-core/classes
     [copy] Copying 186 files to /Andromeda/Users/tredmond/dev/workspaces/protege3/protege-core/classes
     [copy] Copied 4 empty directories to 1 empty directory under /Andromeda/Users/tredmond/dev/workspaces/protege3/protege-core/classes

jar:
     [copy] Copying 1 file to /Andromeda/Users/tredmond/dev/workspaces/protege3/protege-core/dist
      [jar] Building jar: /Andromeda/Users/tredmond/dev/workspaces/protege3/protege-core/dist/protege.jar

install:
     [copy] Copying 1 file to /tmp/Protege3
     [copy] Copying 1 file to /tmp/Protege3
     [copy] Copying 1 file to /tmp/Protege3
     [copy] Copying 9 files to /tmp/Protege3
     [copy] Copying 12 files to /tmp/Protege3/examples
    [mkdir] Created dir: /tmp/Protege3/plugins
    [mkdir] Created dir: /tmp/Protege3/logs

BUILD SUCCESSFUL
Total time: 40 seconds
[tredmond@Andromeda protege-core]$ 

At this point you can go to the Protege 3 installation and run it and it will be able to load frames projects. This is the most basic Protege 3 installation. The PROTEGE_HOME environment variable has only been used to determine the location to install Protege. Note that this installation process is portable - it works on any java platform with ant - and it does not depend on any particular directory structure, the existence of any executables (other than ant and java) or the system configuration.

Now we will add owl.


[tredmond@Andromeda protege-owl]$ cd ../protege-owl
[tredmond@Andromeda protege-owl]$ svn info
Path: .
URL: http://smi-protege/repos/protege/owl/trunk
Repository Root: http://smi-protege/repos/protege
Repository UUID: 30a32298-b1ee-0310-87e3-a7336bc3aa68
Revision: 14650
Node Kind: directory
Schedule: normal
Last Changed Author: tredmond
Last Changed Rev: 14605
Last Changed Date: 2009-06-19 11:08:35 -0700 (Fri, 19 Jun 2009)

[tredmond@Andromeda protege-owl]$ ant clean
Buildfile: build.xml

clean:
   [delete] Deleting directory /Andromeda/Users/tredmond/dev/workspaces/protege3/protege-owl/build

BUILD SUCCESSFUL
Total time: 4 seconds
[tredmond@Andromeda protege-owl]$ ant install
Buildfile: build.xml

checkProtegeHome:

useProtegeHome:
     [echo] Using Protege Home = /tmp/Protege3 to find protege jars

useLibDir:

checkProtegeLibs:

checkProtegeLibsAndReport:

init.time:

init:
    [mkdir] Created dir: /Andromeda/Users/tredmond/dev/workspaces/protege3/protege-owl/build
    [mkdir] Created dir: /Andromeda/Users/tredmond/dev/workspaces/protege3/protege-owl/build/classes
    [mkdir] Created dir: /Andromeda/Users/tredmond/dev/workspaces/protege3/protege-owl/build/dist
    [mkdir] Created dir: /Andromeda/Users/tredmond/dev/workspaces/protege3/protege-owl/build/plugins

compile:
    [javac] Compiling 1526 source files to /Andromeda/Users/tredmond/dev/workspaces/protege3/protege-owl/build/classes
    [javac] Note: Some input files use or override a deprecated API.
    [javac] Note: Recompile with -Xlint:deprecation for details.
    [javac] Note: Some input files use unchecked or unsafe operations.
    [javac] Note: Recompile with -Xlint:unchecked for details.
     [copy] Copying 334 files to /Andromeda/Users/tredmond/dev/workspaces/protege3/protege-owl/build/classes
     [copy] Copied 63 empty directories to 56 empty directories under /Andromeda/Users/tredmond/dev/workspaces/protege3/protege-owl/build/classes

jar:
     [copy] Copying 1 file to /Andromeda/Users/tredmond/dev/workspaces/protege3/protege-owl/build
      [jar] Building jar: /Andromeda/Users/tredmond/dev/workspaces/protege3/protege-owl/build/dist/protege-owl.jar

plugin.dir:
    [mkdir] Created dir: /Andromeda/Users/tredmond/dev/workspaces/protege3/protege-owl/build/plugins/edu.stanford.smi.protegex.owl
     [copy] Copying 49 files to /Andromeda/Users/tredmond/dev/workspaces/protege3/protege-owl/build/plugins/edu.stanford.smi.protegex.owl

plugin.zip:
      [zip] Building zip: /Andromeda/Users/tredmond/dev/workspaces/protege3/protege-owl/build/dist/protege-owl.zip

install:
    [unzip] Expanding: /Andromeda/Users/tredmond/dev/workspaces/protege3/protege-owl/build/dist/protege-owl.zip into /tmp/Protege3/plugins
     [copy] Copying 2 files to /tmp/Protege3/examples/pizza
     [copy] Copying 2 files to /tmp/Protege3/examples/travel
     [copy] Copying 2 files to /tmp/Protege3/examples/family

BUILD SUCCESSFUL
Total time: 1 minute 1 second
[tredmond@Andromeda protege-owl]$ 

Now the Protege installation can load owl files.

Now the Protege owl build process depends on the protege.jar library that we built in the previous build step. Often developers deal with this by including a copy of the protege.jar file in the lib directory that is checked out by svn. But this approach creates problems because the protege.jar file in the lib directory gets out of date. Developers need to continually update this file leading to svn conflicts. Maven has an excellent approach to solving this problem in the form of repositories. We have chosen a different approach that does not have all the advantages of maven repositories but which is much simpler and works well enough for our needs. What happens in the above build file is that the Protege owl build process finds the protege.jar in the Protege installation directory. This means that the PROTEGE_HOME environment variable is used both to determine where to install owl and to determine where to find the needed dependencies. This makes it easy to build plugins with dependencies by building the dependencies first. It is also very easy to construct build scripts that build one protege plugin after another (e.g. the nci build script.

Now just to drill the point home, we will build one more plugin. This plugin is the standard extensions plugin which depends on both the protege.jar library and the protege-owl.jar library. Since the PROTEGE_HOME environment variable points to the latest protege.jar and protege-owl.jar, the standard-extensions plugin builds without any problems.


[tredmond@Andromeda standard-extensions]$ cd ../standard-extensions
[tredmond@Andromeda standard-extensions]$ svn info
Path: .
URL: http://smi-protege/repos/protege/standard-extensions/trunk
Repository Root: http://smi-protege/repos/protege
Repository UUID: 30a32298-b1ee-0310-87e3-a7336bc3aa68
Revision: 14650
Node Kind: directory
Schedule: normal
Last Changed Author: tredmond
Last Changed Rev: 14621
Last Changed Date: 2009-06-27 11:02:22 -0700 (Sat, 27 Jun 2009)

[tredmond@Andromeda standard-extensions]$ ant clean
Buildfile: build.xml

clean:
   [delete] Deleting directory /Andromeda/Users/tredmond/dev/workspaces/protege3/standard-extensions/build

BUILD SUCCESSFUL
Total time: 1 second
[tredmond@Andromeda standard-extensions]$ ant install
Buildfile: build.xml

init:
    [mkdir] Created dir: /Andromeda/Users/tredmond/dev/workspaces/protege3/standard-extensions/build
    [mkdir] Created dir: /Andromeda/Users/tredmond/dev/workspaces/protege3/standard-extensions/build/classes
    [mkdir] Created dir: /Andromeda/Users/tredmond/dev/workspaces/protege3/standard-extensions/build/plugins
    [mkdir] Created dir: /Andromeda/Users/tredmond/dev/workspaces/protege3/standard-extensions/build/plugins/edu.stanford.smi.protegex.standard_extensions

checkProtegeLibs:
     [echo] Using Protege Home = /tmp/Protege3 to find protege jars

checkProtegeLibsAndReport:

compile:
    [javac] Compiling 257 source files to /Andromeda/Users/tredmond/dev/workspaces/protege3/standard-extensions/build/classes
    [javac] Note: /Andromeda/Users/tredmond/dev/workspaces/protege3/standard-extensions/src/edu/stanford/smi/protegex/widget/uri/Icons.java uses or overrides a deprecated API.
    [javac] Note: Recompile with -Xlint:deprecation for details.
    [javac] Note: Some input files use unchecked or unsafe operations.
    [javac] Note: Recompile with -Xlint:unchecked for details.
     [copy] Copying 19 files to /Andromeda/Users/tredmond/dev/workspaces/protege3/standard-extensions/build/classes
     [copy] Copied 4 empty directories to 1 empty directory under /Andromeda/Users/tredmond/dev/workspaces/protege3/standard-extensions/build/classes

images:
    [mkdir] Created dir: /Andromeda/Users/tredmond/dev/workspaces/protege3/standard-extensions/build/images
    [unjar] Expanding: /tmp/Protege3/protege.jar into /Andromeda/Users/tredmond/dev/workspaces/protege3/standard-extensions/build/images
     [copy] Copying 1 file to /Andromeda/Users/tredmond/dev/workspaces/protege3/standard-extensions/build/plugins/edu.stanford.smi.protegex.standard_extensions/html_export/images
     [copy] Copying 10 files to /Andromeda/Users/tredmond/dev/workspaces/protege3/standard-extensions/build/plugins/edu.stanford.smi.protegex.standard_extensions/html_export/images

jar:
     [copy] Copying 1 file to /Andromeda/Users/tredmond/dev/workspaces/protege3/standard-extensions/build
     [copy] Copying 5 files to /Andromeda/Users/tredmond/dev/workspaces/protege3/standard-extensions/build/plugins/edu.stanford.smi.protegex.standard_extensions/html_export
      [jar] Building jar: /Andromeda/Users/tredmond/dev/workspaces/protege3/standard-extensions/build/plugins/edu.stanford.smi.protegex.standard_extensions/standard-extensions.jar
     [copy] Copying 2 files to /Andromeda/Users/tredmond/dev/workspaces/protege3/standard-extensions/build/plugins/edu.stanford.smi.protegex.standard_extensions
     [copy] Copying 1 file to /Andromeda/Users/tredmond/dev/workspaces/protege3/standard-extensions/build/plugins/edu.stanford.smi.protegex.standard_extensions
     [copy] Copying 1 file to /Andromeda/Users/tredmond/dev/workspaces/protege3/standard-extensions/build/plugins/edu.stanford.smi.protegex.standard_extensions

dist:
      [zip] Building zip: /Andromeda/Users/tredmond/dev/workspaces/protege3/standard-extensions/build/standard-extensions.zip

install:
    [unzip] Expanding: /Andromeda/Users/tredmond/dev/workspaces/protege3/standard-extensions/build/standard-extensions.zip into /tmp/Protege3/plugins

BUILD SUCCESSFUL
Total time: 14 seconds
[tredmond@Andromeda standard-extensions]$ 

Troubleshooting

Missing protege libraries

First make sure that your PROTEGE_HOME environment variable is pointing to a real Protege distribution. This message is telling you that there is some library that this plugin depends on that is