source: general/prog/mercurial.xml@ 4b76422

<?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 mercurial-download-http "https://www.mercurial-scm.org/release/mercurial-&mercurial-version;.tar.gz">
  <!ENTITY mercurial-download-ftp  " ">
  <!ENTITY mercurial-md5sum        "4826ab69616e1d647b2ca9eb28bf9ade">
  <!ENTITY mercurial-size          "7.9 MB">
  <!ENTITY mercurial-buildsize     "113 MB (with docs, add 1.5 GB for tests)">
  <!ENTITY mercurial-time          "0.3 SBU (with docs; add 16 SBU for tests; both using parallelism=8)">
]>

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


  <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 for Firefox and Thunderbird.
    </para>

    &lfs121_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">Optional</bridgehead>
    <para role="optional">
      <xref linkend="docutils"/>
        (required to build the documentation),
      <xref linkend="git"/>,
      <xref linkend="gpgme"/> (with Python bindings),
      <xref role="runtime" linkend="openssh"/>
        (runtime, to access ssh://... repositories),
      <xref linkend="pygments"/>,
      <xref linkend="rust"/> (see <filename>rust/README.rst</filename> and <filename>rust/rhg/README.md</filename>),
      <xref linkend="subversion"/> (with Python bindings),
      <ulink url="https://launchpad.net/bzr">Bazaar</ulink>,
      <ulink url="https://www.nongnu.org/cvs/">CVS</ulink>,
      <ulink url="https://pypi.python.org/pypi/pyflakes">pyflakes</ulink>,
      <ulink url="https://www.pyopenssl.org/en/stable/">pyOpenSSL</ulink>, and
      <ulink url="https://github.com/google/re2/">re2</ulink>
    </para>

  </sect2>

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

    <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>
<!--
    The tests do not hang.  Better to just report what failed.

    [renodr]: The tests do crash due to syntax errors and crash before they get
    to the Python portion (which is where most of Mercurial is)
-->

    <para>
      If you wish to run the tests, the rust tests must be removed as they are
      currently broken due to syntax errors. To do this, issue:
    </para>

<screen><userinput>sed -i '138,142d' Makefile</userinput></screen>

    <para>
      To run the test suite, issue:
    </para>
<screen remap="test"><userinput>TESTFLAGS="-j<replaceable>&lt;N&gt;</replaceable> --tmpdir tmp" 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 README.
     For 6.4.1 removing the -blacklist entries did not affect the test results
     although blacklists/fsmonitor and blacklists/linux-vfat still exist. -->

    <para>
      where <replaceable>&lt;N&gt;</replaceable> is an integer between one
      and the number of ( processor X threads ), inclusive. Tests may
      fail because some error messages have changed in Python or
      some deprecation warnings are printed that were not present when the
      test was designed.  Two tests are known to fail: test-duplicateoptions.py
      and test-profile.t.
    </para>
      <!--
      # Ran 908 tests, 65 skipped, 4 failed.  real  10m37.422s -bdubbs  6 Sep 22.
      # Ran 881 tests,102 skipped, 23 failed.                  -plabs  17 Nov 22.
      # Ran 919 tests, 64 skipped, 23 failed. real  10m25.285s -bdubbs 10 Jan 23.
      # Ran 893 tests,101 skipped,  9 failed. real  29m03.014s -bdubbs  5 Mar 23.
      # Ran 938 tests, 64 skipped,  8 failed. real  32m13.014s -bdubbs 17 Apr 23.
      # Ran 935 tests, 69 skipped,  8 failed. real  26m15.875s -bdubbs 10 Jun 23.
      # Ran 940 tests, 64 skipped,  8 failed. real  omitted    -bdubbs 26 Jun 23.
      # Ran 948 tests, 66 skipped, 0 failed. -pierre 12 Jul 23 (mercurial-6.5).
      # Ran 950 tests, 65 skipped, 1 failed. -pierre 8  Nov 23 (mercurial-6.5.3).
      # Ran 948 tests, 66 skipped, 0 failed. -renodr 22 Nov 23 (mercurial-6.6).
      # Ran 946 tests, 71 skipped, 2 failed. -bdubbs 20 Mar 24 (mercurial-6.7).
      # Ran 966 tests, 58 skipped, 1 failed. -renodr 16 Mar 24 (mercurial-6.8).
      -->
    <para>
      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 reproducible. However, if
      you add the switch <option>--debug</option> before
      <option>--tmpdir</option>, and run the tests again, some failures may
      disappear, which is a problem with the test suite. If this happens,
      there will be no more of these failures even if you do not pass the
      --debug switch again.
    </para>

    <para>
      An interesting switch is <option>--time</option>, which will generate a
      table of all the executed tests and their respective start, end, user,
      system and real times once the tests are complete. Note that these
      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>
      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. This will output a list of enabled
        and disabled extensions, as well as more information such as how to
        enable or disable extensions using configuration files.
      </para>

      <para>
        If you have installed <xref linkend="make-ca"/> and want
        <application>Mercurial</application> to use the certificates,
        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,
          /usr/lib/python&python3-majorver;/site-packages/hgdemandimport,
          /usr/lib/python&python3-majorver;/site-packages/hgext,
          /usr/lib/python&python3-majorver;/site-packages/hgext3rd,
          /usr/lib/python&python3-majorver;/site-packages/mercurial, and
          /usr/lib/python&python3-majorver;/site-packages/mercurial-&mercurial-version;-py&python3-majorver;.egg-info
        </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>