source: general/prog/mercurial.xml@ b037ef4

<?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        "c5ff220fba5f5bda93e6679e4ce57e0c">
  <!ENTITY mercurial-size          "5.9 MB">
  <!ENTITY mercurial-buildsize     "62 MB (add 587 MB for tests)">
  <!ENTITY mercurial-time          "0.3 SBU (add 7.9 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>

    &lfs82_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="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>,
    <ulink url="http://pygments.org/">pygments</ulink>, and
    <ulink url="https://github.com/pyca/pyopenssl">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>

    <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><userinput>make doc</userinput></screen>

<!-- All tests pass (or are skipped) at version 3.8.2
    <para>Running the test suite is optional. Tests which fail may be disabled,
    adding each one to <filename>tests/blacklists/failed-tests</filename>. In
    order to execute the test suite using the temporary directory <filename
    class="directory">tests/tmp</filename> and skipping the failing tests,
    issue:</para>

<screen><userinput>cat &gt; tests/blacklists/failed-tests &lt;&lt; "EOF"
<literal># Test Failures
  test-gpg.t</literal>
EOF
-->
    <para>
      To run the test suite, issue:
    </para>
<screen><userinput>rm -rf tests/tmp &amp;&amp;
TESTFLAGS="-j<replaceable>&lt;N&gt;</replaceable> --tmpdir tmp --blacklist blacklists/failed-tests" make check</userinput></screen>

    <para>where <replaceable>&lt;N&gt;</replaceable> is an integer between one
    and the number of ( processor X threads ), inclusive. One test, test-gpg.t,
    fails if <xref linkend="gnupg2"/> is not installed. One other test,
    test-bundle2-exchange.t, is known to fail.  In order to investigate any
    other 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><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
    "--debug" before "--tmpdir", 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.</para>

    <para>An interesting switch is "- -time", 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. Notice that the switches may be
    used with <command>make check</command>, 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"><userinput>make PREFIX=/usr install-doc</userinput></screen>

    <para>After installed, two very quick and simple tests should run correctly.
    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="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/ssl/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&python2-majorver;/site-packages/mercurial
        </seg>
        <seg>
          /etc/mercurial and
          /usr/lib/python&python2-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 program file for mercurial.</para>
          <indexterm zone="mercurial hg">
            <primary sortas="b-hg">hg</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>