EXPath

You can you XProject either form oXygen, or from the command-line. If you use oXygen, the easiest is to use the plugin. If you want to use XProject from the command-line, you can either download it manually from this page and install the XAR file, or you can install it automatically from CXAN, with the ID xproject.

XProject helps you organizing an XML project and performing usual actions on it. All you have to do is respecting a specific project structure and giving some meta-informations in a project descriptor. In this documentation, when we use the term project, we refer to such a directory, following the same structure conventions and containing a project descriptor.

The project structure as such is very simple: the name of the project directory is free, and it must contain two sub-directories:

• src/ containing the sources of the project, that is, the code you want to write
• xproject/ contains the project descriptor, as well as any other meta-informations about your project; the project descriptor is an XML file called xproject/project.xml

The project can also contain the following sub-directories:

• dist/ is automatically generated and contain the result of building your project
• test/ is where you put your unit tests, which can be run automatically by XProject
• resources/ is ignored and is a convenient place to put anything that is not part of the delivery of your project (that won't be delivered as part of the XAR file) but that takes part of the project (e.g. some scripts or development tools)

Here is an example of a project:

my-lib/
   resources/
      backup.xproc
      internal-schema.xsd
   src/
      the-lib.xsl
      other-lib.xql
      resource.xml
   xproject/
      project.xml

The above project contains three files as part of the deliverable material. It also contains a project descriptor, and two resources used by the developers of that project. The project descriptor looks like the following:

<project xmlns="http://expath.org/ns/project"
         name="http://example.org/my-lib"
         abbrev="my-lib"
         version="1.3.0">

   <title>Example library</title>

   <home>http://example.org/tools/my-lib/index.html</home>

</project>

Basically, the project descriptor has the same structure as a package descriptor, but in the XProject namespace, without the component descriptors. That is, it does not describe explicitly the XSLT and XQuery components it contains (in this example). Each component contains an annotation with its own public URI (sometimes it can be infered, like for XML Schemas and XQuery library modules, which have a target URI). When one builds the project, XProject will automatically introspect the components and build the corresponding package descriptor.

Here are the content of the two components of the project. The XSLT stylesheet src/the-lib.xsl contains (note the packaging annotation):

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
                xmlns:pkg="http://expath.org/ns/pkg"
                version="2.0">

   <pkg:import-uri>http://example.org/ns/my-lib/the-lib.xsl</pkg:import-uri>

   ...

</xsl:stylesheet>

and the XQuery library module (note it does not contain annotations, as an XQuery library module already has a traget namespace, which is parsed during building the package) (note also it contains xquerydoc comments to be formatted with xproj doc):

(:~
 : Sample library module.
 :
 : @author Florent Georges - H2O Consulting
 : @version 1.0.0
 : @see http://expath.org/
 :)
module namespace lib = "http://example.org/other-lib";

(:~
 : Return greetings (an element) from a name (which is used as content).
 :
 : @since 1.0.0
 : @param $who The name to create greetings for.
 : @return Return greetings as en element.
 : @error There is no error.
 :)
declare function lib:hello-world($who as item())
{
  <greetings>Hello, { $who }!</greetings>
};

So once you set your project up (providing a few meta-informations), you usualy don't have to maintain anymore the project descriptor. If you want to add a new public component, just create it somewhere in src/, and add the corresponding annotation directly in it. No need to update any other file, so no descriptor is becoming outdated.

We describe here how to use XProject from within the command-line. The oXygen plugin contains a toolbar with buttons for all of the corresponding actions, as well as new templates for standard components like XSLT and XQuery, with XProject annotations. This description assumes you have correctly installed the XProject XAR file and have the xproj shell script in your $PATH. You might have to adapt the command to your system though. The shell script is just a wrapper around calling Calabash with the correct pipelines for a specific action, but you are encouraged to use it.

The xproj command always expects to be called within a project directory. So first cd to your project, then you can invoke xproj. You have several actions available:

• build to build the XAR file (or XAW file for a webapp)
• test to run the unit tests
• doc to generate the documentation out of the components (like Javadoc for Java, for now understands only xquerydoc)
• release to build a release file (a ZIP file containing the XAR file, sources, and other stuff)

Assuming we have the above example project in /projects/my-lib/ and that we have xproj in the shell $PATH, the following command will create the XAR file:

# cd /projects/my-lib

# xproj build
Building project file:/projects/my-lib/
Generated XAR file dist/my-lib-1.3.0.xar

# 

As you can see, it uses informations from the project descriptor to name the XAR file following the convention "dist/[abbrev]-[version].xar". If the directory xproject/ contains a CXAN descriptor (that is, a file named xproject/cxan.xml) and/or a webapp descriptor (that is, a file names xproject/expath-web.xml), those will be properly added to the generated package. New actions "publish" and "deploy", still to implement, will allow one to automatically publish the package to CXAN and to deploy it on a webapp container, respectively.