source: general/prog/subversion.xml@ 2998eb65

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY subversion-download-http "https://archive.apache.org/dist/subversion/subversion-&subversion-version;.tar.bz2">
  <!ENTITY subversion-download-ftp  " ">
  <!ENTITY subversion-md5sum        "be9f6c5e8bb80e465152b4c5160d7f54">
  <!ENTITY subversion-size          "8.1 MB">
  <!-- for 1.12.0                    1.12.2         1.13.0
       make javahl: 0.5 SBU  28 MB; not avail
       swig-pl:     0.8      42 MB; 0.7 SBU  43 MB; 0.6 SBU 44 MB
       swig-py:     0.6      26 MB; 0.5      28 MB; 0.5     28 MB
       swig-rb:     0.4      22 MB; 0.4      21 MB; 0.3     21 MB
       docs:        2 secs   26 MB; 2 sec    27 MB; 2 sec   26 MB
       tests       46 min  1104 MB  46:52  1103 MB  47 min   -->
  <!ENTITY subversion-buildsize     "193 MB (add 189 MB for bindings, 54 MB for docs, 1.3 GB for tests)">
  <!ENTITY subversion-time          "0.4 SBU (Using parallelism=4; add 2.0 SBU for bindings, 30 SBU for tests)">
]>

<sect1 id="subversion" xreflabel="Subversion-&subversion-version;">
  <?dbhtml filename="subversion.html"?>


  <title>Subversion-&subversion-version;</title>

  <indexterm zone="subversion">
    <primary sortas="a-Subversion">Subversion</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to Subversion</title>

    <para>
      <application>Subversion</application> is a version control system that is
      designed to be a compelling replacement for <application>CVS</application>
      in the open source community. It extends and enhances
      <application>CVS</application>' feature set, while maintaining a similar
      interface for those already familiar with <application>CVS</application>.
      These instructions install the client and server software used to
      manipulate a <application>Subversion</application> repository. Creation of
      a repository is covered at <xref linkend="svnserver"/>.
    </para>

    &lfs122_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Download (HTTP): <ulink url="&subversion-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&subversion-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &subversion-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &subversion-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &subversion-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &subversion-time;
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Subversion Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required">
      <xref linkend="apr-util"/> and
      <xref linkend="sqlite"/>
    </para>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <xref linkend="serf"/> (for handling http:// and https:// URLs) and
      <xref linkend="swig"/> (for regenerating the build system)
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="apache"/>,
      <xref linkend="boost"/>,
      <xref linkend="cyrus-sasl"/>,
      <xref linkend="dbus"/>,
      <xref linkend="doxygen"/> (for generating HTML documentation),
      <xref linkend="gnome-keyring"/>,
      <xref linkend="libsecret"/>,
      <xref linkend="py3c"/> (for the python bindings, and tests),
      <xref linkend="python3"/> (with sqlite support for the tests),
      <xref linkend="ruby"/>, and
      <ulink url="https://git.netsurf-browser.org/libutf8proc.git/">UTF8proc</ulink>
    </para>

    <bridgehead renderas="sect4">Optional (for the Java Bindings)</bridgehead>
    <para role="optional">
      One of <xref linkend="openjdk"/>,
      <ulink url="https://www.inet.no/dante/">Dante</ulink> or
      <ulink url="https://jikes.sourceforge.net/">Jikes</ulink>,
      <ulink url="https://junit.org/junit4/">JUnit 4</ulink> (to test the Java bindings) and
      <xref linkend="apache-ant"/>.
    </para>

  </sect2>

  <sect2 role="installation">
    <title>Installation of Subversion</title>

    <para>
      Install <application>Subversion</application> by running the following
      commands:
    </para>

<screen><userinput>PYTHON=python3                        \
./configure --prefix=/usr             \
            --disable-static          \
            --with-apache-libexecdir  \
            --with-utf8proc=internal &amp;&amp;
make</userinput></screen>

    <para>
      If you have <xref linkend="doxygen"/> installed and you wish to build the
      API documentation, issue:
    </para>

<screen remap="doc"><userinput>doxygen doc/doxygen.conf</userinput></screen>

    <para>
      If you wish to build the Java bindings pass the <option>--enable-javahl</option>
      parameter to the <command>configure</command> command. In addition, if
      you want to run the Java test suite, you have to specify the location
      of the <application>JUnit</application> file by adding
      <option>--with-junit=&lt;path to junit jar&gt;</option> (for
      instance <option>--with-junit=/usr/local/java/lib/junit-4.13.jar</option>)
      to <command>configure</command>. The JUnit jar file is no longer
      included in <xref linkend="apache-ant"/> and must be downloaded
      separately. To build the Java bindings, issue the following command:
    </para>

    <para>
      <screen><command>make -j1 javahl</command></screen>
    </para>

    <para>
      If you want to compile <application>Perl</application>,
      <application>Python</application>, or <application>Ruby</application>
      bindings, issue any of the following command:
    </para>

<screen><command>make swig-pl</command> # for <application>Perl</application>
<command>make swig-py \
     swig_pydir=/usr/lib/python&python3-majorver;/site-packages/libsvn \
     swig_pydir_extra=/usr/lib/python&python3-majorver;/site-packages/svn</command> # for <application>Python</application>
<command>make swig-rb</command> # for <application>Ruby</application></screen>

    <para>
      To test the results, issue: <command>make check</command>. Four tests in
      the <filename>commit_tests.py</filename>,
      <filename>prop_tests.py</filename>, and
      <filename>update_tests.py</filename> suites are known to fail. Due to
      changes in Python-3.12, you can expect to see around 200 Syntax Warnings
      during the test suite due to invalid escape sequences.
    </para>

    <para>
      To test the results of any of the <application>SWIG</application>
      bindings, you can use any of the following commands:
      <command>make check-swig-pl</command>,
      <command>make check-swig-py</command>, or
      <command>make check-swig-rb</command>.
    </para>

    <para>
      Now, as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>make install &amp;&amp;

install -v -m755 -d /usr/share/doc/subversion-&subversion-version; &amp;&amp;
cp      -v -R doc/* /usr/share/doc/subversion-&subversion-version;</userinput></screen>

    <para>
      If you built the Java bindings, issue the following command as the
      <systemitem class="username">root</systemitem> user to install them:
    </para>
    <para>
<screen><command>make install-javahl</command></screen>
    </para>

    <para>
      If you built the <application>Perl</application>,
      <application>Python</application>, or
      <application>Ruby</application> bindings, issue any of the following
      commands as the <systemitem class="username">root</systemitem> user
      to install them:
    </para>
    <para>
<screen><command>make install-swig-pl</command>
<command>make install-swig-py \
      swig_pydir=/usr/lib/python&python3-majorver;/site-packages/libsvn \
      swig_pydir_extra=/usr/lib/python&python3-majorver;/site-packages/svn</command>
<command>make install-swig-rb</command></screen>
    </para>

    <para>
      The java bindings need to be installed in order for the tests to run,
      since the tests attempt to look for them in CLASSPATH. To test the
      results of the Java bindings build, issue
      <command>LANG=C make check-javahl</command>.
      <!-- ~~ This explanation is added to the configure above ~~
      The <application>JUnit</application> testing framework must be installed,
      and the location of the JUnit jar has to be specified by passing the
      <option>- -with-junit=&lt;path to junit jar&gt;</option> parameter to
      <command>configure</command>. Note that <application>JUnit</application>
      is included in <xref linkend="apache-ant"/>, and can be accessed by
      passing <option>- -with-junit=/opt/ant/lib/junit-4.12.jar</option>
      to <command>configure</command>.
      -->
    </para>
  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="../../xincludes/static-libraries.xml"/>

    <para>
      <parameter>--with-apache-libexecdir</parameter>:
      If <xref linkend="apache"/> is installed, the shared
      <application>Apache</application> modules are
      built. This switch allows to have those modules installed to
      <application>Apache</application>'s configured module dir instead
      of <filename class="directory">/usr/libexec</filename>. It has no effect
      if <application>Apache</application> is not installed.
    </para>

    <para>
      <parameter>--with-utf8proc=internal</parameter>:
      Remove these switches if you have installed the optional dependencies.
    </para>

    <para>
      <option>--enable-javahl</option>: enables compilation of Java high level
      bindings. Running <command>make javahl</command> is necessary to do
      the compilation.
    </para>

    <para>
      <option>--with-junit=&lt;location of the junit jar file&gt;</option>:
      gives the location of the junit jar, otherwise the javahl tests cannot
      be run.
    </para>

    <para>
      <option>--disable-gmock</option>: Do not use the Googlemock testing
      framework.
    </para>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring Subversion</title>

    <sect3 id="subversion-config">
      <title>Config Files</title>

      <para>
        <filename>~/.subversion/config</filename> and
        <filename>/etc/subversion/config</filename>
      </para>

      <indexterm zone="subversion subversion-config">
        <primary sortas="e-AA.subversion/config">~/.subversion/config</primary>
      </indexterm>

      <indexterm zone="subversion subversion-config">
        <primary sortas="e-etc-subversion-config">/etc/subversion/config</primary>
      </indexterm>
    </sect3>

    <sect3>
      <title>Configuration Information</title>

      <para>
        <filename>/etc/subversion/config</filename> is the
        <application>Subversion</application> system-wide configuration file.
        This file is used to specify defaults for different
        <command>svn</command> commands.
      </para>

      <para>
        <filename>~/.subversion/config</filename> is the user's personal
        configuration file. It is used to override the system-wide defaults set
        in <filename>/etc/subversion/config</filename>.
      </para>
    </sect3>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>
          svn, svnadmin, svnbench, svndumpfilter, svnfsfs, svnlook, svnmucc,
          svnrdump, svnserve, svnsync, and svnversion
        </seg>
        <seg>
          libsvn_*-1.so and optionally, a Java library, the mod_dav_svn.so and
          mod_authz_svn.so <application>Apache HTTP</application> DSO
          modules and various <application>Perl</application>,
          <application>Python</application> and
          <application>Ruby</application> modules.
        </seg>
        <seg>
          /usr/include/subversion-1,
          /usr/lib/perl5/site_perl/&lfs-perl-version;/{,auto/}SVN,
          /usr/lib/python&python3-majorver;/site-packages/{libsvn,svn},
          /usr/lib/ruby/site_ruby/&lt;x.y.z&gt;/{,&lt;arch-linux&gt;-linux/}svn,
          /usr/lib/svn-javahl, and
          /usr/share/doc/subversion-&subversion-version;
        </seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="svn">
        <term><command>svn</command></term>
        <listitem>
          <para>
            is a command-line client program used to access
            <application>Subversion</application> repositories
          </para>
          <indexterm zone="subversion svn">
            <primary sortas="b-svn">svn</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="svnadmin">
        <term><command>svnadmin</command></term>
        <listitem>
          <para>
            is a tool for creating, tweaking or repairing a
            <application>Subversion</application> repository
          </para>
          <indexterm zone="subversion svnadmin">
            <primary sortas="b-svnadmin">svnadmin</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="svnbench">
        <term><command>svnbench</command></term>
        <listitem>
          <para>
            is a benchmarking tool
          </para>
          <indexterm zone="subversion svnbench">
            <primary sortas="b-svnbench">svnbench</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="svndumpfilter">
        <term><command>svndumpfilter</command></term>
        <listitem>
          <para>
            is a program for filtering <application>Subversion</application>
            repository dumpfile format streams
          </para>
          <indexterm zone="subversion svndumpfilter">
            <primary sortas="b-svndumpfilter">svndumpfilter</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="svnfsfs">
        <term><command>svnfsfs</command></term>
        <listitem>
          <para>
            is the FSFS (FileSystem atop of the FileSystem -
            <application>Subversion</application> filesystem implementation)
            repository manipulation tool
          </para>
          <indexterm zone="subversion svnfsfs">
            <primary sortas="b-svnfsfs">svnfsfs</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="svnlook">
        <term><command>svnlook</command></term>
        <listitem>
          <para>
            is a tool for inspecting a <application>Subversion</application>
            repository
          </para>
          <indexterm zone="subversion svnlook">
            <primary sortas="b-svnlook">svnlook</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="svnmucc">
        <term><command>svnmucc</command></term>
        <listitem>
          <para>
            is a Multiple URL Command Client for <application>Subversion</application>
          </para>
          <indexterm zone="subversion svnmucc">
            <primary sortas="b-svnmucc">svnmucc</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="svnrdump">
        <term><command>svnrdump</command></term>
        <listitem>
          <para>
            is a tool for dumping or loading a remote
            <application>Subversion</application> repository
          </para>
          <indexterm zone="subversion svnrdump">
            <primary sortas="b-svnrdump">svnrdump</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="svnserve">
        <term><command>svnserve</command></term>
        <listitem>
          <para>
            is a custom standalone server program, able to run as a daemon
            process or invoked by SSH
          </para>
          <indexterm zone="subversion svnserve">
           <primary sortas="b-svnserve">svnserve</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="svnsync">
        <term><command>svnsync</command></term>
        <listitem>
          <para>
            is a <application>Subversion</application> repository
            synchronisation tool
          </para>
          <indexterm zone="subversion svnsync">
           <primary sortas="b-svnsync">svnsync</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="svnversion">
        <term><command>svnversion</command></term>
        <listitem>
          <para>
            is used to report the version number and state of a working
            <application>Subversion</application> repository copy
          </para>
          <indexterm zone="subversion svnversion">
            <primary sortas="b-svnversion">svnversion</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libsvn_star-1">
        <term><filename class="libraryfile">libsvn_*-1.so</filename></term>
        <listitem>
          <para>
            are the support libraries used by the
            <application>Subversion</application> programs
          </para>
          <indexterm zone="subversion libsvn_star-1">
            <primary sortas="c-libsvn_star-1">libsvn_*-1.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="mod_authz_svn">
        <term><filename class="libraryfile">mod_authz_svn.so</filename></term>
        <listitem>
          <para>
            is a plug-in module for the <application>Apache</application> HTTP
            server, used to authenticate users to a
            <application>Subversion</application> repository over the Internet
            or an intranet
          </para>
          <indexterm zone="subversion mod_authz_svn">
            <primary sortas="c-mod_authz_svn">mod_authz_svn.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="mod_dav_svn">
        <term><filename class="libraryfile">mod_dav_svn.so</filename></term>
        <listitem>
          <para>
            is a plug-in module for the <application>Apache</application> HTTP
            server, used to make a <application>Subversion</application>
            repository available to others over the Internet or an intranet
          </para>
          <indexterm zone="subversion mod_dav_svn">
            <primary sortas="c-mod_authz_svn">mod_dav_svn.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>