<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE dmodule>
<dmodule xmlns:dc="http://www.purl.org/dc/elements/1.1/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.s1000d.org/S1000D_5-0/xml_schema_flat/descript.xsd">
  <identAndStatusSection>
    <dmAddress>
      <dmIdent>
        <dmCode modelIdentCode="S1KDTOOLS" systemDiffCode="A" systemCode="00" subSystemCode="0" subSubSystemCode="0" assyCode="00" disassyCode="00" disassyCodeVariant="A" infoCode="920" infoCodeVariant="A" itemLocationCode="D"/>
        <language languageIsoCode="en" countryIsoCode="CA"/>
        <issueInfo issueNumber="008" inWork="01"/>
      </dmIdent>
      <dmAddressItems>
        <issueDate year="2024" month="04" day="02"/>
        <dmTitle>
          <techName>s1kd-tools</techName>
          <infoName>Building, installing and uninstalling</infoName>
        </dmTitle>
      </dmAddressItems>
    </dmAddress>
    <dmStatus issueType="changed">
      <security securityClassification="01"/>
      <responsiblePartnerCompany>
        <enterpriseName>khzae.net</enterpriseName>
      </responsiblePartnerCompany>
      <originator>
        <enterpriseName>khzae.net</enterpriseName>
      </originator>
      <applic>
        <displayText>
          <simplePara>All</simplePara>
        </displayText>
      </applic>
      <brexDmRef>
        <dmRef>
          <dmRefIdent>
            <dmCode modelIdentCode="S1000D" systemDiffCode="G" systemCode="04" subSystemCode="1" subSubSystemCode="0" assyCode="0301" disassyCode="00" disassyCodeVariant="A" infoCode="022" infoCodeVariant="A" itemLocationCode="D"/>
          </dmRefIdent>
        </dmRef>
      </brexDmRef>
      <qualityAssurance>
        <unverified/>
      </qualityAssurance>
      <reasonForUpdate id="rfu-0001" updateHighlight="1">
        <simplePara>Update Linux requirements</simplePara>
      </reasonForUpdate>
      <reasonForUpdate id="rfu-0002" updateHighlight="1">
        <simplePara>Add instructions for Cygwin and MinGW64</simplePara>
      </reasonForUpdate>
    </dmStatus>
  </identAndStatusSection>
  <content>
    <description>
      <levelledPara>
        <title>General</title>
        <para>There are multiple ways to install the s1kd-tools:</para>
        <para>
          <randomList>
            <listItem>
              <para>using a package manager and the pre-compiled Debian (.deb) or Red Hat (.rpm) packages</para>
            </listItem>
            <listItem>
              <para>building from source</para>
            </listItem>
          </randomList>
        </para>
      </levelledPara>
      <levelledPara>
        <title>Using a package manager</title>
        <para>Debian (.deb) and Red Hat (.rpm) packages are provided to easily install, upgrade or uninstall the s1kd-tools on Linux systems using a package manager. The examples below focus on the standard <verbatimText>dpkg</verbatimText> (for Debian-based distributions) and <verbatimText>rpm</verbatimText> (for Red Hat-based distributions).</para>
        <levelledPara>
          <title>Installing</title>
          <para>You can download the latest release of the s1kd-tools from <externalPubRef xlink:href="http://khzae.net/1/s1000d/s1kd-tools/releases/latest">
              <externalPubRefIdent>
                <externalPubCode>http://khzae.net/1/s1000d/s1kd-tools/releases/latest</externalPubCode>
              </externalPubRefIdent>
            </externalPubRef>. Then use one of the following commands to install it:</para>
          <para>
            <emphasis>Debian:</emphasis>
            <verbatimText verbatimStyle="vs24"># dpkg -i s1kd-tools_[version]_[arch].deb</verbatimText>
          </para>
          <para>
            <emphasis>Red Hat:</emphasis>
            <verbatimText verbatimStyle="vs24"># rpm -i s1kd-tools.[version].[arch].rpm</verbatimText>
          </para>
        </levelledPara>
        <levelledPara>
          <title>Uninstalling</title>
          <para>To uninstall using the package manager, use one of the following commands:</para>
          <para>
            <emphasis>Debian:</emphasis>
            <verbatimText verbatimStyle="vs24"># dpkg -r s1kd-tools</verbatimText>
          </para>
          <para>
            <emphasis>Red Hat:</emphasis>
            <verbatimText verbatimStyle="vs24"># rpm -e s1kd-tools</verbatimText>
          </para>
        </levelledPara>
      </levelledPara>
      <levelledPara>
        <title>Building from source</title>
        <levelledPara>
          <title>Requirements</title>
          <para>To build the executables:</para>
          <para>
            <randomList changeMark="1" changeType="modify" reasonForUpdateRefIds="rfu-0001">
              <listItem>
                <para>coreutils</para>
              </listItem>
              <listItem>
                <para>binutils</para>
              </listItem>
              <listItem>
                <para>gcc</para>
              </listItem>
              <listItem>
                <para>make</para>
              </listItem>
              <listItem>
                <para>xxd</para>
              </listItem>
              <listItem>
                <para>pkg-config</para>
              </listItem>
              <listItem>
                <para>
                  <externalPubRef xlink:href="http://xmlsoft.org">
                    <externalPubRefIdent>
                      <externalPubCode>http://xmlsoft.org</externalPubCode>
                      <externalPubTitle>libxml2, libxslt, libexslt</externalPubTitle>
                    </externalPubRefIdent>
                  </externalPubRef>
                </para>
              </listItem>
              <listItem>
                <para>
                  <emphasis>If using the <verbatimText>SAXON</verbatimText> XPath engine: </emphasis>
                  <externalPubRef xlink:href="https://www.saxonica.com/saxon-c/index.xml">
                    <externalPubRefIdent>
                      <externalPubCode>https://www.saxonica.com/saxon-c/index.xml</externalPubCode>
                      <externalPubTitle>Saxon/C</externalPubTitle>
                    </externalPubRefIdent>
                  </externalPubRef>
                </para>
              </listItem>
              <listItem>
                <para>
                  <emphasis>If using the <verbatimText>XQILLA</verbatimText> XPath engine: </emphasis>
                  <externalPubRef xlink:href="https://xerces.apache.org/xerces-c/">
                    <externalPubRefIdent>
                      <externalPubCode>https://xerces.apache.org/xerces-c/</externalPubCode>
                      <externalPubTitle>Xerces-C</externalPubTitle>
                    </externalPubRefIdent>
                  </externalPubRef>,
                  <externalPubRef xlink:href="http://xqilla.sourceforge.net/HomePage">
                    <externalPubRefIdent>
                      <externalPubCode>http://xqilla.sourceforge.net</externalPubCode>
                      <externalPubTitle>XQilla</externalPubTitle>
                    </externalPubRefIdent>
                  </externalPubRef>
                </para>
              </listItem>
            </randomList>
          </para>
          <para>To build the documentation from source:</para>
          <para>
            <randomList>
              <listItem>
                <para>
                  <externalPubRef xlink:href="http://github.com/kibook/s1kd2db">
                    <externalPubRefIdent>
                      <externalPubCode>http://github.com/kibook/s1kd2db</externalPubCode>
                      <externalPubTitle>s1kd2db</externalPubTitle>
                    </externalPubRefIdent>
                  </externalPubRef>
                </para>
              </listItem>
              <listItem>
                <para>
                  <externalPubRef xlink:href="https://pandoc.org/">
                    <externalPubRefIdent>
                      <externalPubCode>https://pandoc.org/</externalPubCode>
                      <externalPubTitle>pandoc</externalPubTitle>
                    </externalPubRefIdent>
                  </externalPubRef>
                </para>
              </listItem>
            </randomList>
          </para>
        </levelledPara>
        <levelledPara>
          <title>Windows build environment</title>
          <para>To build the executables on Windows, an environment such as MinGW or Cygwin is recommended. These provide POSIX-compatible tools, such as <verbatimText>make</verbatimText>, that allow the s1kd-tools to be built and installed on a Windows system in the same way as on a Linux system.</para>
          <levelledPara changeMark="1" changeType="add" reasonForUpdateRefIds="rfu-0002">
            <title>Cygwin</title>
            <para>To build the executables on Cygwin, you will need the following packages from the package installer:</para>
            <para>
              <randomList>
                <listItem>
                  <para>binutils</para>
                </listItem>
                <listItem>
                  <para>gcc-core</para>
                </listItem>
                <listItem>
                  <para>make</para>
                </listItem>
                <listItem>
                  <para>xxd</para>
                </listItem>
                <listItem>
                  <para>libxml2-devel</para>
                </listItem>
                <listItem>
                  <para>libxslt-devel</para>
                </listItem>
              </randomList>
            </para>
          </levelledPara>
          <levelledPara changeMark="1" changeType="add" reasonForUpdateRefIds="rfu-0002">
            <title>MSYS2 MINGW64</title>
            <para>Prior to building the executables on MSYS2 MINGW64, run the following to install the necessary packages from pacman:</para>
            <para>
              <verbatimText verbatimStyle="vs24">pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-make mingw-w64-x86_64-pkgconf mingw-w64-x86_64-libxml2 mingw-w64-x86_64-libxslt mingw-w64-x86_64-libsystre vim</verbatimText>
            </para>
          </levelledPara>
        </levelledPara>
        <levelledPara>
          <title>Building and installing</title>
          <para>Run the following commands to build the executables, and install both the executables and documentation:</para>
          <para>
            <verbatimText verbatimStyle="vs24">$ make
# make install</verbatimText>
          </para>
        </levelledPara>
        <levelledPara>
          <title>Uninstalling</title>
          <para>To uninstall the executables and documentation:</para>
          <para>
            <verbatimText verbatimStyle="vs24"># make uninstall</verbatimText>
          </para>
        </levelledPara>
        <levelledPara>
          <title>Additional Makefile parameters</title>
          <para>The following parameters can be given to <verbatimText>make</verbatimText> to control certain options when building and installing.</para>
          <levelledPara>
            <title>
              <verbatimText>PREFIX</verbatimText>
            </title>
            <para>The <verbatimText>PREFIX</verbatimText> variable determines where the s1kd-tools are installed when running <verbatimText>make install</verbatimText>, and where they are uninstalled from when running <verbatimText>make uninstall</verbatimText>. The default value is <verbatimText>/usr/local</verbatimText>.</para>
            <para>
              Example:
              <verbatimText verbatimStyle="vs24"># make PREFIX=/usr install</verbatimText>
              <verbatimText verbatimStyle="vs24"># make PREFIX=/usr uninstall</verbatimText>
            </para>
          </levelledPara>
          <levelledPara>
            <title>
              <verbatimText>XPATH2_ENGINE</verbatimText>
            </title>
            <para>The <verbatimText>XPATH2_ENGINE</verbatimText> variable determines which XPath 2.0 implementation the s1kd-brexcheck tool will use to evaluate the object paths of BREX rules.</para>
            <para>
              The s1kd-tools are built on libxml, so by default s1kd-brexcheck uses libxml's XPath implementation. However, libxml only supports XPath 1.0. While as of Issue 5.0, the S1000D default BREX rules are all compatible with XPath 1.0, Issue 4.0 and up do reference the XPath 2.0 specification. Therefore, if your project needs XPath 2.0 support for BREX rules, you should select one of these implementations:
              <definitionList>
                <definitionListItem>
                  <listItemTerm>
                    <verbatimText>SAXON</verbatimText>
                  </listItemTerm>
                  <listItemDefinition>
                    <para>Experimental implementation using the Saxon/C library. Slower, and Saxon/C itself is a very large dependency. Not recommended at this time due to memory leak issues.</para>
                  </listItemDefinition>
                </definitionListItem>
                <definitionListItem>
                  <listItemTerm>
                    <verbatimText>XQILLA</verbatimText>
                  </listItemTerm>
                  <listItemDefinition>
                    <para>Experimental implementation using the Xerces-C and XQilla libraries. A little slower than libxml, but faster than Saxon/C, and the dependencies are much smaller than the latter. This is currently the recommended implementation if you need XPath 2.0 support.</para>
                  </listItemDefinition>
                </definitionListItem>
              </definitionList>
            </para>
            <para>
              Example:
              <verbatimText verbatimStyle="vs24">$ make XPATH2_ENGINE=XQILLA</verbatimText>
            </para>
          </levelledPara>
        </levelledPara>
      </levelledPara>
    </description>
  </content>
</dmodule>