README for JenaBuild
====================
What is this?
-------------
JenaBuild is the module used to compile, test, package and distribute Jena3.
Jena3 is the third generation of Jena, a Java framework for building semantic
web applications.
Jena3 is composed of five modules:
- JenaCore: core interfaces and implementation, N-Triples reader/writer
- JenaShell: assembler, N3/Turtle readers/writers
- JenaMem: an in memory graph implementation
- JenaRules: an forward inference engine
- JenaXML: XML reader/writer and pretty printing
JenaShell and JenaMem depend on JenaCore. JenaRules and JenaXML depend on
JenaShell and therefore, indirectly, on JenaCore.
JenaBuild doesn't contain code itself. We use Ant+Ivy to test, package and
distribute Jena3 while we use Eclipse IDE as development platform.
Requirements
------------
JenaBuild requires:
- A Java v1.6 or later Java Virtual Machine for your operating system.
- Ant v1.7 or later installed on your system.
- Ivy v2.0.0-beta2 or later installed on your system.
- A network connection and, if you are behind a web proxy, ANT_OPTS
properly configured as explained in [1].
How do I use it?
----------------
Developers can check out each Jena3 module using Eclipse and pointing at the
Jena3 Subversion repository, currently at:
- https://svn.hpl.hp.com/svnroot/jena
To check out Jena3 modules below Jena3\trunk, select one or more folders
(i.e. JenaCore, JenaMem, etc.), right click and select "Checkout...".
All Jena3 modules come with configuration files for Eclipse and no plug-ins
are required to be able to work with them.
Developers that need to build a Jena3 release or want to use Ant need to
checkout JenaBuild together with all the other Jena3 modules. This can be
done with Eclipse or it could be done via command line:
- svn co https://svn.hpl.hp.com/svnroot/jena/Jena3/trunk Jena3
Once the Jena3 project has been checked out, it is possible to invoke the
Ant+Ivy targets defined in the build-lib.xml file below the JenaBuild module.
Each module can be compiled/tested/released separately and JenaBuild can
compile/test/release the union of all the modules.
You can type ant -p to see a list of the available Ant targets. A list of
the main targets with a description of what a target does follows:
clean Cleanup
Use this to delete all the files and directories that have been
automatically generated by the build system. The only exception is the
distribution (i.e. ./dist) directory.
clean-build Rebuild the jar(s)
Use this to recompile the entire module and package the jar from a
clean state. The compiled sources are located below ./build/classes
while the jar package is located below ./build/jar.
This works for a single module as well as from JenaBuild. In this
case all the sources will be compiled and packaged into a single
jar file.
compile Compile sources
Use this to incrementally compile the sources. This target doesn't
create any jar file and it works for a single module as well as
from JenaBuild.
ivy-publish Publish (with Ivy) artifact
The build system uses Ivy to publish jar files to a shared repository.
At the moment Ivy is configured to publish artifact on a local
repository, below ~user/.ivy2/local.
This target should be invoked after a release or after a development
cycle when a developer wants to push a new jar to other developers
that are working on modules that depend on that jar.
ivy-setup-lib Resolve dependencies using Ivy
This target should be invoked when a developer want to check if new
jars are available. Ivy will download new jars and copy them below
the ./lib directory.
Dependencies are defined for each module in the ivy.xml file.
Every time a dependency change, the .classpath Eclipse file needs
to be updated.
release Create release
Use this to release a module or to do a release for all the modules.
This target generates a release below the ./dist directory.
When invoked from JenaBuild the release will include the code from all
the other modules.
report Run tests and generate reports
Use this to run the tests with JUnit and generate reports of the
result in HTML format.
You can see the reports starting from: ./reports/html/index.html
If you run this target from JenaBuild, all the tests for all the
modules will be executed and a global report will be generated.
test Run the test suites without generating reports
This will run the tests without generating any report.
(work in progress)
The idea is to have the usual functionalities (compile, setup-lib, jar,
release, test, report) working in the same way for each module as well
as from JenaBuild. When a target is called from JenaBuild the action
will be performed on all the modules and the result will be generated
below ./JenaBuild and it will include files from all the other modules.
How do I add a new module?
--------------------------
We do not expect having the need to create a new module very often,
so, at the moment, creating a new Jena3 module is a manual process.
To add a new module, first of all, create a new directory at the
same level where the other modules are located.
Copy from an existing module the following files:
- .classpath
- .project
- build.xml
- ivy.xml
Change the JenaMem in .project. You can change the content
of .classpath file using Eclipse.
Edit the build.xml and change the project name for the tag and
in the "Name" and "name" properties. You should also change the version-*
properties. Everything else should be ok to start. Each build.xml in each
Jena3 module imports build-lib.xml from JenaBuild. The only things that
a module needs to do are:
- provide a java.build.class.path path reference
- provide a java.run.class.path path reference
- provide a java.src.all path reference
- provide a java.test.src.all path reference
- provide a target named "zip-src" to build a zip with all the sources
These paths need to be defined after the if they use properties
defined by build-lib.xml.
In this way we share common Ant targets across all the modules still
allowing each module to have different source directories. If all the
modules will have the exact directories layout we could have shared
definitions for the path references and avoid personalised zip-src
targets.
We could also import properties from a build.property file and have
an almost empty build.xml.
(work in progress)
The Jena3 team
[1] http://ant.apache.org/manual/proxy.html