source: general/sysutils/gpm.xml

trunk
Last change on this file was b9874725, checked in by Bruce Dubbs <bdubbs@…>, 2 months ago

Many tags.

Mostly Programming and Xorg sections and dependencies.

  • Property mode set to 100644
File size: 14.9 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
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 gpm-download-http "&sources-anduin-http;/gpm/gpm-&gpm-version;.tar.bz2">
8 <!ENTITY gpm-download-ftp " ">
9 <!ENTITY gpm-md5sum "bf84143905a6a903dbd4d4b911a2a2b8">
10 <!ENTITY gpm-size "820 KB">
11 <!ENTITY gpm-buildsize "7.4 MB">
12 <!ENTITY gpm-time "0.1 SBU">
13]>
14
15<sect1 id="gpm" xreflabel="GPM-&gpm-version;">
16 <?dbhtml filename="gpm.html"?>
17
18
19 <title>GPM-&gpm-version;</title>
20
21 <indexterm zone="gpm">
22 <primary sortas="a-GPM">GPM</primary>
23 </indexterm>
24
25 <sect2 role="package">
26 <title>Introduction to GPM</title>
27
28 <para>
29 The <application>GPM</application> (General Purpose Mouse daemon)
30 package contains a mouse server for the console and
31 <command>xterm</command>. It not only provides cut and paste support
32 generally, but its library component is used by various software such as
33 <application>Links</application> to provide mouse support to the
34 application. It is useful on desktops, especially if following (Beyond)
35 Linux From Scratch instructions; it's often much easier (and less error
36 prone) to cut and paste between two console windows than to type
37 everything by hand!
38 </para>
39
40 &lfs121_checked;
41
42 <bridgehead renderas="sect3">Package Information</bridgehead>
43 <itemizedlist spacing="compact">
44 <listitem>
45 <para>
46 Download (HTTP): <ulink url="&gpm-download-http;"/>
47 </para>
48 </listitem>
49 <listitem>
50 <para>
51 Download (FTP): <ulink url="&gpm-download-ftp;"/>
52 </para>
53 </listitem>
54 <listitem>
55 <para>
56 Download MD5 sum: &gpm-md5sum;
57 </para>
58 </listitem>
59 <listitem>
60 <para>
61 Download size: &gpm-size;
62 </para>
63 </listitem>
64 <listitem>
65 <para>
66 Estimated disk space required: &gpm-buildsize;
67 </para>
68 </listitem>
69 <listitem>
70 <para>
71 Estimated build time: &gpm-time;
72 </para>
73 </listitem>
74 </itemizedlist>
75
76 <bridgehead renderas="sect3">Additional Downloads</bridgehead>
77 <itemizedlist spacing="compact">
78 <listitem>
79 <para>
80 Required patch:
81 <ulink url="&patch-root;/gpm-&gpm-version;-consolidated-1.patch"/>
82 </para>
83 </listitem>
84 </itemizedlist>
85
86 <bridgehead renderas="sect3">GPM Dependencies</bridgehead>
87
88 <bridgehead renderas="sect4">Optional</bridgehead>
89 <para role="optional">
90 <xref linkend="texlive"/> (for documentation)
91 </para>
92 </sect2>
93
94 <sect2 role="kernel" id='gpm-kernel'>
95 <title>Kernel Configuration</title>
96
97 <para>
98 Enable the following option in the kernel configuration and recompile the
99 kernel if necessary:
100 </para>
101
102 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
103 href="gpm-kernel.xml"/>
104
105 <indexterm zone="gpm gpm-kernel">
106 <primary sortas="d-gpm">gpm</primary>
107 </indexterm>
108
109 </sect2>
110
111 <sect2 role="installation">
112 <title>Installation of GPM</title>
113
114 <para>
115 Install <application>GPM</application> by running
116 the following commands:
117 </para>
118
119<screen><userinput>patch -Np1 -i ../gpm-&gpm-version;-consolidated-1.patch &amp;&amp;
120./autogen.sh &amp;&amp;
121./configure --prefix=/usr --sysconfdir=/etc ac_cv_path_emacs=no &amp;&amp;
122make</userinput></screen>
123
124 <para>
125 If <xref linkend='texlive'/> is installed, build the GPM manual as
126 dvi, ps, and pdf formats:
127 </para>
128
129<screen remap='doc'><userinput>make -C doc gpm.{dvi,ps} &amp;&amp;
130dvipdfm doc/gpm.dvi -o doc/gpm.pdf</userinput></screen>
131
132 <para>
133 This package does not come with a test suite.
134 </para>
135
136 <para>
137 Now, as the <systemitem class="username">root</systemitem> user:
138 </para>
139
140<screen role="root"><userinput>make install &amp;&amp;
141
142install-info --dir-file=/usr/share/info/dir \
143 /usr/share/info/gpm.info &amp;&amp;
144
145rm -fv /usr/lib/libgpm.a &amp;&amp;
146ln -sfv libgpm.so.2.1.0 /usr/lib/libgpm.so &amp;&amp;
147install -v -m644 conf/gpm-root.conf /etc &amp;&amp;
148
149install -v -m755 -d /usr/share/doc/gpm-&gpm-version;/support &amp;&amp;
150install -v -m644 doc/support/* \
151 /usr/share/doc/gpm-&gpm-version;/support &amp;&amp;
152install -v -m644 doc/{FAQ,HACK_GPM,README*} \
153 /usr/share/doc/gpm-&gpm-version;</userinput></screen>
154
155 <para>
156 If <xref linkend='texlive'/> is installed and you've built GPM
157 manual as dvi, ps, and pdf formats, install them as the &root; user:
158 </para>
159
160<screen role='root' remap='doc'><userinput>install -vm644 doc/gpm.{dvi,ps,pdf} /usr/share/doc/gpm-&gpm-version;</userinput></screen>
161
162 </sect2>
163
164 <sect2 role="commands">
165 <title>Command Explanations</title>
166
167 <para>
168 <command>./autogen.sh</command>: This command creates the missing
169 <command>configure</command> script.
170 </para>
171
172 <para>
173 <parameter>ac_cv_path_emacs=no</parameter>: This variable works around
174 an issue causing the package fail to build with
175 <xref linkend='emacs'/> installed. It also suppresses the
176 installations of some <quote>Emacs support files</quote> shipped with
177 GPM. These files are quite outdated and they should be superseded
178 with <xref linkend='emacs'/> built-in GPM support. If you need to use
179 <xref linkend='emacs'/> in Linux console with mouse support, you
180 should install (or reinstall) <xref linkend='emacs'/>
181 <emphasis role='bold'>after</emphasis> GPM.
182 </para>
183
184 <para>
185 <command>install-info ...</command>: This package installs a
186 <filename class="extension">.info</filename> file, but does not update
187 the system <filename>dir</filename> file. This command makes the update.
188 </para>
189
190 <para>
191 <command>ln -v -sfn libgpm.so.2.1.0 /usr/lib/libgpm.so</command>: This
192 command is used to create (or update) the <filename
193 class="extension">.so</filename> symlink to the library.
194 </para>
195
196 </sect2>
197
198 <sect2 role="configuration">
199 <title>Configuring GPM</title>
200
201 <sect3 id="gpm-init">
202 <title><phrase revision="sysv">Boot Script</phrase>
203 <phrase revision="systemd">Systemd Unit</phrase></title>
204
205 <indexterm zone="gpm gpm-init">
206 <primary sortas="f-gpm-init">gpm</primary>
207 </indexterm>
208
209 <para revision="sysv">
210 Install the
211 <filename>/etc/rc.d/init.d/gpm</filename> init script included in the
212 <xref linkend="bootscripts"/> package.
213 </para>
214
215 <para revision="systemd">
216 To start the <command>gpm</command> daemon at boot,
217 install the systemd unit from the <xref linkend="systemd-units"/>
218 package by running the following command as the
219 <systemitem class="username">root</systemitem> user:
220 </para>
221
222<screen role="root"><userinput>make install-gpm</userinput></screen>
223
224 </sect3>
225
226 <sect3 id="gpm-config">
227 <title>Config Files</title>
228
229 <para>
230 <filename>/etc/gpm-root.conf</filename> and
231 <filename>~/.gpm-root</filename>: The default and individual user
232 <command>gpm-root</command> configuration files.
233 </para>
234
235 <para revision="sysv">
236 <filename>/etc/sysconfig/mouse</filename>:
237 This file contains the name of your mouse device and the protocol
238 it uses. To create this file, run the following as the
239 <systemitem class="username">root</systemitem> user:
240 </para>
241
242<screen role="root" revision="sysv"><userinput>cat &gt; /etc/sysconfig/mouse &lt;&lt; "EOF"
243<literal># Begin /etc/sysconfig/mouse
244
245MDEVICE="<replaceable>&lt;yourdevice&gt;</replaceable>"
246PROTOCOL="<replaceable>&lt;yourprotocol&gt;</replaceable>"
247GPMOPTS="<replaceable>&lt;additional options&gt;</replaceable>"
248
249# End /etc/sysconfig/mouse</literal>
250EOF</userinput></screen>
251
252 <indexterm zone="gpm gpm-config">
253 <primary sortas="e-AA.gpm-root">~/.gpm-root</primary>
254 </indexterm>
255
256 <indexterm zone="gpm gpm-config">
257 <primary sortas="e-etc-gpm-root.conf">/etc/gpm-root.conf</primary>
258 </indexterm>
259
260 <indexterm zone="gpm gpm-config" revision="sysv">
261 <primary sortas="e-etc-sysconfig-mouse">/etc/sysconfig/mouse</primary>
262 </indexterm>
263
264 </sect3>
265
266 <sect3>
267 <title>Configuration Information</title>
268
269 <para revision="sysv">
270 Examples of values to set <envar>MDEVICE</envar>,
271 <envar>PROTOCOL</envar>, and <envar>GPMOPTS</envar> to are:
272 </para>
273
274<screen revision="sysv"><literal>MDEVICE="/dev/input/mice"
275PROTOCOL="imps2"
276GPMOPTS=""</literal></screen>
277
278 <para revision="sysv">
279 A list of which protocol values are known can be found by running
280 <command>gpm -m <replaceable>[device]</replaceable> -t -help</command>.
281 The <envar>MDEVICE</envar> setting depends on which type of mouse you
282 have. For example, <filename>/dev/ttyS0</filename> for a serial mouse
283 (on Windows this is COM1), <filename>/dev/input/mice</filename> is
284 often used for USB mice and <filename>/dev/psaux</filename> for PS2
285 mice. <envar>GPMOPTS</envar> is the 'catch all' for any additional
286 options that are needed for your hardware.
287 </para>
288
289 <para revision="systemd">
290 <application>GPM</application> is by default started with
291 the following parameters:
292 <parameter>-m /dev/input/mice -t imps2</parameter>. If the
293 mentioned parameters don't suit your needs, you can override
294 them by running the following commands as
295 the <systemitem class="username">root</systemitem> user:
296 </para>
297
298<screen role="nodump" revision="systemd"><userinput>install -v -dm755 /etc/systemd/system/gpm.service.d &amp;&amp;
299cat &gt; /etc/systemd/system/gpm.service.d/99-user.conf &lt;&lt; EOF
300<literal>[Service]
301ExecStart=/usr/sbin/gpm <replaceable>&lt;list of parameters&gt;</replaceable>
302</literal>EOF</userinput></screen>
303
304 </sect3>
305
306 </sect2>
307
308 <sect2 role="content">
309 <title>Contents</title>
310
311 <segmentedlist>
312 <segtitle>Installed Programs</segtitle>
313 <segtitle>Installed Library</segtitle>
314 <segtitle>Installed Directory</segtitle>
315
316 <seglistitem>
317 <seg>disable-paste, display-buttons, display-coords, get-versions, gpm,
318 gpm-root, hltest, mev, and mouse-test</seg>
319 <seg>libgpm.so</seg>
320 <seg>/usr/share/doc/gpm-&gpm-version;</seg>
321 </seglistitem>
322 </segmentedlist>
323
324 <variablelist>
325 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
326 <?dbfo list-presentation="list"?>
327 <?dbhtml list-presentation="table"?>
328
329 <varlistentry id="disable-paste">
330 <term><command>disable-paste</command></term>
331 <listitem>
332 <para>
333 is a security mechanism used to disable the paste buffer
334 </para>
335 <indexterm zone="gpm disable-paste">
336 <primary sortas="b-disable-paste">disable-paste</primary>
337 </indexterm>
338 </listitem>
339 </varlistentry>
340
341 <varlistentry id="display-buttons">
342 <term><command>display-buttons</command></term>
343 <listitem>
344 <para>
345 is a simple program that reports the mouse buttons being
346 pressed and released
347 </para>
348 <indexterm zone="gpm display-buttons">
349 <primary sortas="b-display-buttons">display-buttons</primary>
350 </indexterm>
351 </listitem>
352 </varlistentry>
353
354 <varlistentry id="display-coords">
355 <term><command>display-coords</command></term>
356 <listitem>
357 <para>
358 is a simple program that reports the mouse coordinates
359 </para>
360 <indexterm zone="gpm display-coords">
361 <primary sortas="b-display-coords">display-coords</primary>
362 </indexterm>
363 </listitem>
364 </varlistentry>
365
366 <varlistentry id="get-versions">
367 <term><command>get-versions</command></term>
368 <listitem>
369 <para>
370 is used to report the <application>GPM</application> library
371 and server versions
372 </para>
373 <indexterm zone="gpm get-versions">
374 <primary sortas="b-get-versions">get-versions</primary>
375 </indexterm>
376 </listitem>
377 </varlistentry>
378
379 <varlistentry id="gpm-prog">
380 <term><command>gpm</command></term>
381 <listitem>
382 <para>
383 is a cut and paste utility and mouse server for virtual consoles
384 </para>
385 <indexterm zone="gpm gpm-prog">
386 <primary sortas="b-gpm">gpm</primary>
387 </indexterm>
388 </listitem>
389 </varlistentry>
390
391 <varlistentry id="gpm-root">
392 <term><command>gpm-root</command></term>
393 <listitem>
394 <para>
395 is a default handler for <command>gpm</command>. It is used to
396 draw menus on the root window
397 </para>
398 <indexterm zone="gpm gpm-root">
399 <primary sortas="b-gpm-root">gpm-root</primary>
400 </indexterm>
401 </listitem>
402 </varlistentry>
403
404 <varlistentry id="hltest">
405 <term><command>hltest</command></term>
406 <listitem>
407 <para>
408 is a simple sample application using the high-level library, meant
409 to be read by programmers trying to use the high-level library
410 </para>
411 <indexterm zone="gpm hltest">
412 <primary sortas="b-hltest">hltest</primary>
413 </indexterm>
414 </listitem>
415 </varlistentry>
416
417 <varlistentry id="mev">
418 <term><command>mev</command></term>
419 <listitem>
420 <para>
421 is a program to report mouse events
422 </para>
423 <indexterm zone="gpm mev">
424 <primary sortas="b-mev">mev</primary>
425 </indexterm>
426 </listitem>
427 </varlistentry>
428
429 <varlistentry id="mouse-test">
430 <term><command>mouse-test</command></term>
431 <listitem>
432 <para>
433 is a tool for determining the mouse type and device it's
434 attached to
435 </para>
436 <indexterm zone="gpm mouse-test">
437 <primary sortas="b-mouse-test">mouse-test</primary>
438 </indexterm>
439 </listitem>
440 </varlistentry>
441
442 <varlistentry id="libgpm">
443 <term><filename class="libraryfile">libgpm.so</filename></term>
444 <listitem>
445 <para>
446 contains the API functions to access the
447 <application>GPM</application> daemon
448 </para>
449 <indexterm zone="gpm libgpm">
450 <primary sortas="c-libgpm">libgpm.so</primary>
451 </indexterm>
452 </listitem>
453 </varlistentry>
454
455 </variablelist>
456
457 </sect2>
458
459</sect1>
Note: See TracBrowser for help on using the repository browser.