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