source: general/prog/mercurial.xml@ af652fc

<?xml version="1.0" encoding="ISO-8859-1"?>
<!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 mercurial-download-http "https://www.mercurial-scm.org/release/mercurial-&mercurial-version;.tar.gz">
  <!ENTITY mercurial-download-ftp  " ">
  <!ENTITY mercurial-md5sum        "b2ffa0bab0836d6d7dfac24419d2aa7c">
  <!ENTITY mercurial-size          "7.4 MB">
  <!ENTITY mercurial-buildsize     "79 MB (with docs, add 1.1 GB for tests)">
  <!ENTITY mercurial-time          "0.4 SBU (with docs, add 10 SBU for tests using -j4)">
]>

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

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <title>Mercurial-&mercurial-version;</title>

  <indexterm zone="mercurial">
    <primary sortas="a-mercurial">mercurial</primary>
  </indexterm>

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

    <para>
      <application>Mercurial</application> is a distributed source control
      management tool similar to <application>Git</application> and
      <application>Bazaar</application>. <application>Mercurial</application>
      is written in <application>Python</application> and is used by projects
      such as Mozilla and Vim.
    </para>

    &lfs91_checked;

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

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

    <!--
    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required">
      <xref linkend="python2"/>
    </para>
    -->

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
    <xref linkend="docutils"/>
      (required to build the documentation),
    <xref linkend="git"/>,
    <xref linkend="gnupg2"/> (<command>gpg2</command> with Python bindings),
    <xref role="runtime" linkend="openssh"/>
      (runtime, to access ssh://... repositories),
    <xref linkend="pygments"/>,
    <xref linkend="rust"/>,
    <xref linkend="subversion"/> (with Python bindings),
    <ulink url="https://launchpad.net/bzr">Bazaar</ulink>,
    <ulink url="http://www.nongnu.org/cvs/">CVS</ulink>,
    <ulink url="https://pypi.python.org/pypi/pyflakes">pyflakes</ulink>, and
    <ulink url="https://www.pyopenssl.org/en/stable/">pyOpenSSL</ulink>

    </para>

    <para condition="html" role="usernotes">User Notes:
    <ulink url="&blfs-wiki;/mercurial"/></para>

  </sect2>

  <sect2 role="installation">
    <title>Installation of Mercurial</title>
    <!-- Rust port is now part of the standard tests -->

    <para>
      First, force the build system to use Python 3:
    </para>

<screen><userinput remap="pre">export PYTHON=python3</userinput></screen>

    <para>
      Build <application>Mercurial</application> by issuing the following
      command:
    </para>

<screen><userinput>make build</userinput></screen>

    <para>
      To build the documentation (requires <xref linkend="docutils"/>), issue:
    </para>

<screen remap="doc"><userinput>make doc</userinput></screen>

    <para>
      To run the test suite, issue:
    </para>
<screen remap="test"><userinput>TESTFLAGS="-j<replaceable>&lt;N&gt;</replaceable> --tmpdir tmp --blacklist blacklists/fsmonitor --blacklist blacklists/linux-vfat" make check</userinput></screen>
<!-- The blacklists have to be checked every release of Mercurial, do a listing
     of tests/blacklists, but do not include the makefile. -->

    <para>
      where <replaceable>&lt;N&gt;</replaceable> is an integer between one
      and the number of ( processor X threads ), inclusive.  In order to
      investigate any apparently failing tests, you may use the
      <command>run-tests.py</command> script. To see the almost forty switches,
      some of them very useful, issue <command>tests/run-tests.py
      --help</command>.  Running the following commands, you will execute only
      the tests that failed before:
    </para>

<screen remap="test"><userinput>pushd tests  &amp;&amp;
  rm -rf tmp &amp;&amp;
  ./run-tests.py --tmpdir tmp test-gpg.t
popd</userinput></screen>

    <para>
      Normally, the previous failures will be confirmed. However, if
      you add the switch <option>--debug</option> before
      <option>--tmpdir</option>, and run again, some failures are gone, which
      seems to be a problem with the test suite. If this happens, normally,
      from now on, there will be no more such failures whether you use the
      debug switch or not. One test, test-doctest.py, is known to fail.
    </para>

    <para>
      An interesting switch is <option>--time</option>, which will generate at
      the end of the test suite execution, a table with all executed tests and
      respective start, end, user, system and real times. Note that the
      switches may be used with <command>make check</command> by including
      them in the <envar>TESTFLAGS</envar> environment variable.
    </para>

    <para>
      Install <application>Mercurial</application> by running the following
      command (as <systemitem class="username">root</systemitem>):
    </para>

<screen role="root"><userinput>make PREFIX=/usr install-bin</userinput></screen>

    <para>
      If you built the documentation, install it by running the following
      command (as <systemitem class="username">root</systemitem>):
    </para>

<screen role="root"
        remap="doc"><userinput>make PREFIX=/usr install-doc</userinput></screen>

    <para>
      Next, clean up the environment variable set earlier:
    </para>

<screen><userinput>unset PYTHON</userinput></screen>

    <para>
      After installation, two very quick and simple tests should run 
      correctly. The first one needs some configuration:
    </para>

<screen><userinput>cat &gt;&gt; ~/.hgrc &lt;&lt; "EOF"
<literal>[ui]
username = <replaceable>&lt;user_name&gt; &lt;user@mail&gt;</replaceable></literal>
EOF</userinput></screen>

    <para>
      where you must replace &lt;user_name&gt; and &lt;your@mail&gt; (mail
      is optional and can be omitted). With the user identity defined, run
      <command>hg debuginstall</command> and several lines will be displayed,
      the last one reading "no problems detected". Another quick and simple
      test is just <command>hg</command>, which should output basic commands
      that can be used with <command>hg</command>.
    </para>

  </sect2>

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

      <para>
        <command>2to3 -w doc/hgmanpage.py</command>: Since <application>
        Python 3</application> is used with docutils, one file needs to be
        converted in order to be compatible.
      </para>

   </sect2>
-->
   
  <sect2 role="configuration">
    <title>Configuring Mercurial</title>

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

      <para>
        <filename>/etc/mercurial/hgrc</filename> and
        <filename>~/.hgrc</filename>
      </para>

      <indexterm zone="mercurial mercurial-config">
        <primary sortas="e-etc-mercurial-hgrc">/etc/mercurial/hgrc</primary>
      </indexterm>

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

      <para>
        The great majority of extensions are disabled by default. Run
        <command>hg help extensions</command> if you need to enable any, e.g.
        when investigating test failures. You will obtain the lists of enabled
        and disabled extensions, and more information, such as how to enable
        or disable them using configuration files.
      </para>

      <para>
        If you have installed <xref linkend="make-ca"/> and want
        <application>Mercurial</application> to use them, as the <systemitem
        class="username">root</systemitem> user, issue:
      </para>

<screen role="root"><userinput>install -v -d -m755 /etc/mercurial &amp;&amp;
cat &gt; /etc/mercurial/hgrc &lt;&lt; "EOF"
<literal>[web]
cacerts = /etc/pki/tls/certs/ca-bundle.crt</literal>
EOF</userinput></screen>

    </sect3>

  </sect2>

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

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

      <seglistitem>
        <seg>
          hg
        </seg>
        <seg>
          several internal modules under
          /usr/lib/python&python3-majorver;/site-packages/mercurial
        </seg>
        <seg>
          /etc/mercurial and
          /usr/lib/python&python3-majorver;/site-packages/{hgdemandimport,hgext,hgext3rd,mercurial}
        </seg>
      </seglistitem>
    </segmentedlist>

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

      <varlistentry id="hg">
        <term><command>hg</command></term>
        <listitem>
          <para>
            is the mercurial version control system.
          </para>
          <indexterm zone="mercurial hg">
            <primary sortas="b-hg">hg</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>