FAQ

Questions

What does CXAN contain?

CXAN offers a variety of packages, from simple tool libraries to entire web applications. It is based on the EXPath packaging system. The package format supports technologies such as XQuery, Javascript, XSLT, RDF, XML Schema, SPARQL, and more.

Each package has its own package page on the website, containing more information about it. The website can be searched for packages, or simply browsed.

Where is the REST API?

You can access CXAN information using a read-only REST-like API. Just use the same URLs as for the website, but add the HTTP header Accept: application/xml. You will get back a simple XML representation of the information shown on the corresponding webpage.

Who maintain packages?

The packages on CXAN are maintained by a community of volunteers. Each package is assigned to one maintainer. Each package page contains more information about its maintainer.

How are packages maintained?

Technically, packages are maintained in Git repositories. CXAN monitors some specific repositories. Each maintainer has his/her own repository, containing all the packages he/she maintains. Each Git repository has a specific structure, defined by CXAN (basically containing packages in a specific directory structure, based on conventions, besides a few config informations kept in a couple of XML files).

The community collaboration approach using Git.

Maintainers simply maintain the packages they are responsible for in their own Git repository, using all the Git tools they want. As soon as they push changes to the remote repository (well, as soon as CXAN pull these changes), like adding a new version of an existing package, the change becomes available on the CXAN website.

Why using Git?

By using Git, there is no need to implement a security mechanism, or a form to upload new packages. Maintainers can use all Git tools, as they are used to, possibly entire teams collaborating, or using several branches to map their development and release process, as they do for any other piece of software.

By using Git, having a copy of each repository on (at the very least) the remote host, the maintainer local machine and the CXAN website, effectively creates as much backup of each repository on different locations, and maintained and backed up each by different persons or companies or organizations. The updates are transmitted by following the chain of Git pushes. The risk of loosing anything is very low (virtually inexistant), without even having to write any backup strategy.

GitHub does not allow binaries!

CXAN does not use GitHub (except for its own source code). It uses Git. If a maintainer wants to use GitHub, that is its responsibility (I do not think that a couple of small packages, typically less than 100 Ko, is a real problem). I personally use my own server of remote Git repositories.

How can I add a new package to CXAN?

Either you contact a maintainer and convince him/her to add your package (e.g. if the package is related to the maintainer activity). Or you volunteer to become a maintainer yourself. In that case the first step is to create a remote Git repository with the format CXAN expects. Then contact Florent Georges on the EXPath mailing list (or in private if you don't want to write to the mailing list for whatever reason) in order to add your repository to CXAN.

What is the structure of a CXAN repository?

The format is quite simple. If you prefer to learn by example, you can have a look at Florent's personnal repository, or at the EXPath repository.

The root directory must contain a file called packages.xml, with the following format (there must be one element pkg for each package in the repository):

<repo abbrev="my-repo">

   <pkg abbrev="my-library" id="my-repo/my-library">
      <name>http://example.org/lib/super-tools</name>
      <version num="0.1.0">
         <file name="my-library-0.1.0.xar" role="pkg"/>
      </version>
   </pkg>

   <pkg abbrev="web-app-uno" id="my-repo/web-app-uno">
      <name>http://example.org/app/web-app-uno</name>
      <abstract>...</abstract>
      <author id="fgeorges">Florent Georges</author>
      <category id="libs">Libraries</category>
      <category id="saxon">Saxon extensions</category>
      <tag>http</tag>
      <tag>library</tag>
      <tag>saxon</tag>
      <version num="0.11.0dev">
         <dependency processor="http://saxon.sf.net/he"/>
         <file name="expath-http-client-saxon-0.11.0dev.xar" role="pkg"/>
         <file name="expath-http-client-saxon-0.11.0dev.zip" role="archive"/>
      </version>
   </pkg>

</repo>

How do I install a local CXAN?

You can install your own CXAN locally, either to deploy your own local system, or as a package repository maintainer, to double-check your packages before pushing them to http://cxan.org/. In a nutshell, you need to install the following:

First, create a directory which will contain your installation. It will contain Servlex as a sub-directpry, another one will be its application repository, yet another one will be the Git base for the package repositories, and so on. Let us call that directory cxan.home.

To install Servlex, just go to http://servlex.net/, and follow the instructions. The easiest way is to download the installer, and execute it (that is a JAR file, either with a graphical installer, or text-based if your system is text-only). Adapt the directory to cxan.home/servlex. Once it is installed, move the directory cxan.home/servlex/repo to cxan.home/repo and adapt the value of org.expath.servlex.repo.dir accordingly in cxan.home/servlex/conf/catalina.properties.

Adapt the port 19757 to the port number you want to use, in cxan.home/servlex/conf/server.xml. Now you can start Servlex by executing cxan.home/servlex/bin/startup.sh (you might need to set the exec bit on the shell scripts first: chmod u+x *.sh). Go to the Servlex Manager on http://localhost:19757/manager/ (adapt the port number if you changed it in Servlex configuration) to validate it has been installed correctly.

Go to the "Deploy" page of the Servlex Manager, and write down fgeorges/fxsl in the CXAN ID field. Press "Deploy" in order to install the first dependency of the CXAN website application directly from CXAN itself. Confirm the installation. Then go back to the "Deploy' page and repeat this process for the packages fgeorges/pipx, fgeorges/serial and finally the CXAN Website itself: fgeorges/cxan-website. But before testing it, we need to create the Git base directory.

Create the directory cxan.home/git-base/master/. Copy the file cxan.home/repo/cxan-website-0.7.0/content/config-params.xml to cxan.home/repo/config-params.xml, and edit the value of the git-base parameter (make sure that all references to config-params.xml in cxan.home/repo/cxan-website-0.7.0/content/data-access/dir-repos.xpl are pointing to the file (they should all be exactly ../../../../config-params.xml). The value must be an absolute path on your system, starting with file:/, and pointing to the directory cxan.home/git-base/master/ you have just created. Create the file cxan.home/git-base/master/repositories.xml with the following content:

<repositories>

   <repo abbrev="expath" href="../repos/expath/">
      <desc>The EXPath project repository.</desc>
      <packages>../repos/expath/packages.xml</packages>
      <git>
         <remote>http://git.fgeorges.org/r/expath/cxan-repo.git</remote>
         <branch>master</branch>
      </git>
   </repo>

</repositories>

Adapt the values to the package repositories you want to add to your own CXAN deployment, and create a new element repo well, for each such repo. Do not forget to actually clone each of the repositories at the given place.

Create both directpries cxan.home/git-base/master/sanity/ and cxan.home/git-base/master/authors/. And create the file cxan.home/git-base/master/authors.xml with the following content (adapt the content, all author codes in your repositories must exist in this file):

<authors>

   <author id="dnovatchev">
      <name>
         <display>Dimitre Novatchev</display>
      </name>
   </author>

   <author id="fgeorges">
      <name>
         <display>Florent Georges</display>
      </name>
   </author>

   <author id="jkosek">
      <name>
         <display>Jirka Kosek</display>
      </name>
   </author>

   <author id="nwalsh">
      <name>
         <display>Norman Walsh</display>
      </name>
   </author>

   <author id="oasis">
      <name>
         <display>OASIS</display>
      </name>
   </author>

   <author id="pwalmsley">
      <name>
         <display>Priscilla Walmsley</display>
      </name>
   </author>

</authors>

Create cxan.home/git-base/master/categories.xml, with the following content (like for authors, adapt the content, as all category codes in your repositories must exist in this file):

<categories>
   <cat id="applications" name="Applications"/>
   <cat id="databases" name="Databases"/>
   <cat id="doctypes" name="Document types"/>
   <cat id="libs" name="Libraries"/>
   <cat id="pkg" name="Packaging"/>
   <cat id="tools" name="Tools"/>
   <cat id="web-api" name="Web APIs"/>
   <cat id="webapps" name="Webapps"/>
   <cat id="processor" name="Processor-related">
      <cat id="saxon" name="Saxon"/>
      <cat id="exist" name="eXist"/>
      <cat id="calabash" name="Calabash"/>
      <cat id="basex" name="BaseX"/>
   </cat>
</categories>

Now, the last step is to download the CXAN tools. Create the directory cxan.home/tools/, and unzip there the content of the latest file cxan-website-tools-*.zip that you can find on the CXAN page of the CXAN website package. You can then invoke the shell script, with the git-base directory as an option (use an absolute path): ./update-repos.sh cxan.hom/git-base.