source: general/prog/mercurial.xml@ a42c273

10.0 10.1 11.0 11.1 11.2 9.0 9.1 lazarus plabs/python-mods qt5new trunk upgradedb xry111/intltool xry111/soup3 xry111/test-20220226
Last change on this file since a42c273 was a42c273, checked in by Pierre Labastie <pieere@…>, 4 years ago

First round of remap attributes; the "doc" ones + a few "test". Rewrote some
parts so that doc that can be installed with recommended deps is in main
instructions. Also, move doc instructions in <command> tags to <screen>.

git-svn-id: svn://svn.linuxfromscratch.org/BLFS/trunk/BOOK@21613 af4574ff-66df-0310-9fd7-8a98e5e911e0

  • Property mode set to 100644
File size: 9.9 KB
Line 
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4 <!ENTITY % general-entities SYSTEM "../../general.ent">
5 %general-entities;
6
7 <!ENTITY mercurial-download-http "https://www.mercurial-scm.org/release/mercurial-&mercurial-version;.tar.gz">
8 <!ENTITY mercurial-download-ftp " ">
9 <!ENTITY mercurial-md5sum "26e1877d20c921af8da357e1c776d5e5">
10 <!ENTITY mercurial-size "6.9 MB">
11 <!ENTITY mercurial-buildsize "72 MB (add 678 MB for tests)">
12 <!ENTITY mercurial-time "0.4 SBU (add 11 SBU for tests using -j4)">
13]>
14
15<sect1 id="mercurial" xreflabel="Mercurial-&mercurial-version;">
16 <?dbhtml filename="mercurial.html"?>
17
18 <sect1info>
19 <othername>$LastChangedBy$</othername>
20 <date>$Date$</date>
21 </sect1info>
22
23 <title>Mercurial-&mercurial-version;</title>
24
25 <indexterm zone="mercurial">
26 <primary sortas="a-mercurial">mercurial</primary>
27 </indexterm>
28
29 <sect2 role="package">
30 <title>Introduction to Mercurial</title>
31
32 <para><application>Mercurial</application> is a distributed source control
33 management tool similar to <application>Git</application> and
34 <application>Bazaar</application>. <application>Mercurial</application> is
35 written in <application>Python</application> and is used by projects such as
36 Mozilla and Vim.</para>
37
38 &lfs84_checked;
39
40 <bridgehead renderas="sect3">Package Information</bridgehead>
41 <itemizedlist spacing="compact">
42 <listitem>
43 <para>Download (HTTP): <ulink url="&mercurial-download-http;"/></para>
44 </listitem>
45 <listitem>
46 <para>Download (FTP): <ulink url="&mercurial-download-ftp;"/></para>
47 </listitem>
48 <listitem>
49 <para>Download MD5 sum: &mercurial-md5sum;</para>
50 </listitem>
51 <listitem>
52 <para>Download size: &mercurial-size;</para>
53 </listitem>
54 <listitem>
55 <para>Estimated disk space required: &mercurial-buildsize;</para>
56 </listitem>
57 <listitem>
58 <para>Estimated build time: &mercurial-time;</para>
59 </listitem>
60 </itemizedlist>
61
62 <bridgehead renderas="sect3">Mercurial Dependencies</bridgehead>
63
64 <bridgehead renderas="sect4">Required</bridgehead>
65 <para role="required">
66 <xref linkend="python2"/>
67 </para>
68
69 <bridgehead renderas="sect4">Optional</bridgehead>
70 <para role="optional">
71 <xref linkend="docutils"/>
72 (required to build the documentation),
73 <xref linkend="git"/>,
74 <xref linkend="gnupg2"/> (<command>gpg2</command> with Python bindings),
75 <xref role="runtime" linkend="openssh"/>
76 (runtime, to access ssh://... repositories),
77 <xref linkend="pygments"/>,
78 <xref linkend="subversion"/> (with Python bindings),
79 <ulink url="https://launchpad.net/bzr">Bazaar</ulink>,
80 <ulink url="http://www.nongnu.org/cvs/">CVS</ulink>,
81 <ulink url="https://pypi.python.org/pypi/pyflakes">pyflakes</ulink>, and
82 <ulink url="https://github.com/pyca/pyopenssl">pyOpenSSL</ulink>
83
84 </para>
85
86 <para condition="html" role="usernotes">User Notes:
87 <ulink url="&blfs-wiki;/mercurial"/></para>
88
89 </sect2>
90
91 <sect2 role="installation">
92 <title>Installation of Mercurial</title>
93
94 <para>Build <application>Mercurial</application> by issuing the following
95 command:</para>
96
97<screen><userinput>make build</userinput></screen>
98
99 <para>To build the documentation (requires <xref linkend="docutils"/>),
100 issue:</para>
101
102<screen remap="doc"><userinput>sed -i '/runrst/s/N)/N)3/' doc/Makefile &amp;&amp;
1032to3-3.7 -w doc/hgmanpage.py &amp;&amp;
104make doc</userinput></screen>
105
106<!-- All tests pass (or are skipped) at version 3.8.2
107 <para>Running the test suite is optional. Tests which fail may be disabled,
108 adding each one to <filename>tests/blacklists/failed-tests</filename>. In
109 order to execute the test suite using the temporary directory <filename
110 class="directory">tests/tmp</filename> and skipping the failing tests,
111 issue:</para>
112
113<screen remap="test"><userinput>cat &gt; tests/blacklists/failed-tests &lt;&lt; "EOF"
114<literal># Test Failures
115 test-gpg.t</literal>
116EOF
117-->
118 <para>
119 To run the test suite, issue:
120 </para>
121<screen remap="test"><userinput>rm -rf tests/tmp &amp;&amp;
122TESTFLAGS="-j<replaceable>&lt;N&gt;</replaceable> --tmpdir tmp --blacklist blacklists/failed-tests" make check</userinput></screen>
123
124 <para>where <replaceable>&lt;N&gt;</replaceable> is an integer between one
125 and the number of ( processor X threads ), inclusive. In order to
126 investigate any apparently failing tests, you may use the
127 <command>run-tests.py</command> script. To see the almost forty switches,
128 some of them very useful, issue <command>tests/run-tests.py
129 --help</command>. Running the following commands, you will execute only
130 the tests that failed before:</para>
131
132<screen remap="test"><userinput>pushd tests &amp;&amp;
133 rm -rf tmp &amp;&amp;
134 ./run-tests.py --tmpdir tmp test-gpg.t
135popd</userinput></screen>
136
137 <para>Normally, the previous failures will be confirmed. However, if
138 you add the switch
139 "--debug" before "--tmpdir", and run again, some failures are gone, which
140 seems to be a problem with the test suite. If this happens, normally, from
141 now on, there will be no more such failures whether you use the debug switch
142 or not. One test, test-https.t, is known to fail.</para>
143
144 <para>An interesting switch is "--time", which will generate at the end of
145 the test suite execution, a table with all executed tests and respective
146 start, end, user, system and real times. Notice that the switches may be
147 used with <command>make check</command>, including them in the
148 <envar>TESTFLAGS</envar> environment variable.</para>
149
150 <para>Install <application>Mercurial</application> by running the following
151 command (as <systemitem class="username">root</systemitem>):</para>
152
153<screen role="root"><userinput>make PREFIX=/usr install-bin</userinput></screen>
154
155 <para>If you built the documentation, install it by running the following
156 command (as <systemitem class="username">root</systemitem>):</para>
157
158<screen role="root"
159 remap="doc"><userinput>make PREFIX=/usr install-doc</userinput></screen>
160
161 <para>After installed, two very quick and simple tests should run correctly.
162 First one needs some configuration:</para>
163
164<screen><userinput>cat &gt;&gt; ~/.hgrc &lt;&lt; "EOF"
165<literal>[ui]
166username = <replaceable>&lt;user_name&gt; &lt;user@mail&gt;</replaceable></literal>
167EOF</userinput></screen>
168
169 <para>where you must replace &lt;user_name&gt; and &lt;your@mail&gt; (mail
170 is optional and can be omitted). With the user identity defined, run
171 <command>hg debuginstall</command> and several lines will be displayed,
172 the last one reading "no problems detected". Another quick and simple test
173 is just <command>hg</command>, which should output basic commands that can
174 be used with <command>hg</command>.</para>
175
176 </sect2>
177
178 <sect2 role="commands">
179 <title>Command Explanations</title>
180
181 <para>
182 <command>sed -i '/runrst/s/N)/N)3/' doc/Makefile</command>: force use
183 of <application>Python 3</application> for commands using docutils,
184 allowing to use the docutils <application>Python 3</application> module.
185 </para>
186
187 <para>
188 <command>2to3-3.7 -w doc/hgmanpage.py</command>: Since <application>
189 Python 3</application> is used with docutils, one file needs to be
190 converted in order to be compatible.
191 </para>
192
193 </sect2>
194 <sect2 role="configuration">
195 <title>Configuring Mercurial</title>
196
197 <sect3 id="mercurial-config">
198 <title>Config Files</title>
199
200 <para>
201 <filename>/etc/mercurial/hgrc</filename> and
202 <filename>~/.hgrc</filename>
203 </para>
204
205 <indexterm zone="mercurial mercurial-config">
206 <primary sortas="e-etc-mercurial-hgrc">/etc/mercurial/hgrc</primary>
207 </indexterm>
208
209 <indexterm zone="mercurial mercurial-config">
210 <primary sortas="e-AA.hgrc">~/.hgrc</primary>
211 </indexterm>
212
213 <para>The great majority of extensions are disabled by default. Run
214 <command>hg help extensions</command> if you need to enable any, e.g.
215 when investigating test failures. You will obtain the lists of enabled and
216 disabled extensions, and more information, such as how to enable or
217 disable them using configuration files.</para>
218
219 <para>If you have installed <xref linkend="make-ca"/> and want
220 <application>Mercurial</application> to use them, as the <systemitem
221 class="username">root</systemitem> user, issue:</para>
222
223<screen role="root"><userinput>install -v -d -m755 /etc/mercurial &amp;&amp;
224cat &gt; /etc/mercurial/hgrc &lt;&lt; "EOF"
225<literal>[web]
226cacerts = /etc/pki/tls/certs/ca-bundle.crt</literal>
227EOF</userinput></screen>
228
229 </sect3>
230
231 </sect2>
232
233 <sect2 role="content">
234 <title>Contents</title>
235
236 <segmentedlist>
237 <segtitle>Installed Programs</segtitle>
238 <segtitle>Installed Libraries</segtitle>
239 <segtitle>Installed Directories</segtitle>
240
241 <seglistitem>
242 <seg>
243 hg
244 </seg>
245 <seg>
246 several internal modules under
247 /usr/lib/python&python2-majorver;/site-packages/mercurial
248 </seg>
249 <seg>
250 /etc/mercurial and
251 /usr/lib/python&python2-majorver;/site-packages/{hgdemandimport,hgext,hgext3rd,mercurial}
252 </seg>
253 </seglistitem>
254 </segmentedlist>
255
256 <variablelist>
257 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
258 <?dbfo list-presentation="list"?>
259 <?dbhtml list-presentation="table"?>
260
261 <varlistentry id="hg">
262 <term><command>hg</command></term>
263 <listitem>
264 <para>is the program file for mercurial.</para>
265 <indexterm zone="mercurial hg">
266 <primary sortas="b-hg">hg</primary>
267 </indexterm>
268 </listitem>
269 </varlistentry>
270
271 </variablelist>
272
273 </sect2>
274
275</sect1>
Note: See TracBrowser for help on using the repository browser.