doc/installation.xml

   1 <documentation title="CXML Installation">
   2     <h1>Installation of Closure XML</h1>
   3
   4     <a name="download"/>
   5     <h2>Download</h2>
   6     <p>
   7       Download <a href="http://common-lisp.net/project/cxml/download/">tarballs</a> for both cxml itself and closure-common.
   8     </p>
   9     <p>
  10       Or get it from git:
  11     </p>
  12     <p>
  13       <tt>git clone git://repo.or.cz/cxml.git</tt>
  14       (<a href="http://repo.or.cz/w/cxml.git">gitweb</a>)
  15       <br/>
  16
  17       <tt>git clone git://repo.or.cz/closure-common.git</tt>
  18       (<a href="http://repo.or.cz/w/closure-common.git">gitweb</a>)
  19       <br/>
  20     </p>
  21
  22     <a name="implementations"/>
  23     <h2>Implementation-specific notes</h2>
  24     <p>
  25       CXML should be portable to all Common Lisp implementations
  26       supported by <a
  27       href="http://common-lisp.net/project/cl-plus-ssl/#trivial-gray-streams">trivial-gray-streams</a>.
  28     </p>
  29     <p>
  30       On Lisps without Unicode support, cxml uses integers instead of
  31       characters to represent code points internally.  By default,
  32       however, the parser will recode all data to strings containing
  33       characters representing UTF-8 bytes before passing it to user
  34       code.
  35     </p>
  36
  37     <a name="compilation"/>
  38     <h2>Compilation</h2>
  39     <p>
  40       <a href="http://www.cliki.net/asdf">ASDF</a> is used for
  41       compilation.  The following instructions assume that ASDF has
  42       already been loaded.
  43     </p>
  44
  45     <p>
  46       <b>Prerequisites.</b>
  47       CXML needs:
  48       <ul>
  49         <li><a href="http://www.cliki.net/Puri">puri</a></li>
  50         <li><a href="http://www.common-lisp.net/project/cl-plus-ssl/#trivial-gray-streams">trivial-gray-streams</a></li>
  51         <li>
  52           <a href="http://common-lisp.net/project/babel/">Babel</a>
  53           (on Unicode-capable Lisps only)
  54         </li>
  55         <li>
  56           <a href="http://www.cliki.net/closure-common">closure-common</a>
  57           is maintained together with cxml but available as a separate
  58           download (see above for check-out instructions).
  59         </li>
  60       </ul>
  61     </p>
  62
  63     <p>
  64       <b>Compiling and loading CXML.</b>
  65       Register the .asd file, e.g. by symlinking it:
  66     </p>
  67     <pre>$ ln -sf `pwd`/cxml/cxml.asd /path/to/your/registry/
  68 $ ln -sf `pwd`/closure-common/closure-common.asd /path/to/your/registry/</pre>
  69     <p>Then compile CXML using:</p>
  70     <pre>* (asdf:operate 'asdf:load-op :cxml)</pre>
  71
  72     <p>
  73       You can then try the <a href="quickstart.html">quick-start example</a>.
  74     </p>
  75
  76     <a name="tests"/>
  77     <h2>Tests</h2>
  78     <p>Check out the XML and DOM testsuites:</p>
  79     <pre>$ export CVSROOT=:pserver:anonymous@dev.w3.org:/sources/public
  80 $ cvs login    # password is "anonymous"
  81 $ cvs co 2001/XML-Test-Suite/xmlconf
  82 $ cvs co -D '2005-05-06 23:00' 2001/DOM-Test-Suite
  83 $ cd 2001/DOM-Test-Suite &amp;&amp; ant dom1-dtd dom2-dtd</pre>
  84     <p>
  85       Omit <tt>-D</tt> to get the latest version, which may not work
  86       with cxml yet.  The <tt>ant</tt> step is necessary to run the DOM
  87       tests.
  88     </p>
  89     <p>Usage:</p>
  90     <pre>* (xmlconf:run-all-tests "/path/to/2001/XML-Test-Suite/xmlconf/")
  91 * (domtest:run-all-tests "/path/to/2001/DOM-Test-Suite/")
  92 </pre>
  93     <p>
  94       To compare your results with known output, refer to the files
  95       <tt>XMLCONF</tt> and <tt>DOMTEST</tt> in the cxml distribution.
  96     </p>
  97
  98     <p>
  99       <i>fixme</i>: Add an explanation of xml/sax-tests here.
 100     </p>
 101
 102     <p>
 103       <b>fixme</b> domtest.lisp does not understand the current
 104       testsuite driver anymore.&#160; To fix this problem, revert the
 105       affected files manually after check-out:
 106     </p>
 107
 108     <pre>$ cd 2001/XML-Test-Suite/xmlconf/
 109 xmltest$ patch -p0 -R &lt;/path/to/cxml/test/xmlconf-base.diff</pre>
 110
 111     <p>
 112       The log message for the changes reads "<i>Removed unnecessary
 113       xml:base attribute</i>".&#160; If I understand correctly, only
 114       DOM&#160;3 parsers provide the baseURI attribute necessary for
 115       understanding <tt>xmlconf.xml</tt> now.&#160; We don't have that
 116       yet.
 117     </p>
 118 </documentation>