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.