Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML//EN"> |
2 | <HTML> | |
3 | <HEAD> | |
4 | <TITLE>MHonArc v2.5 -- Installation</TITLE> | |
5 | </HEAD> | |
6 | <!-- | |
7 | <BODY background="ssbg75.jpg" | |
8 | text="#000000" link="#0000ee" vlink="#551a8b" alink="ff0000"> | |
9 | --> | |
10 | <BODY> | |
11 | ||
12 | <!--X-NavButtons-Start--> | |
13 | <table width="100%"> | |
14 | <tr valign="top"> | |
15 | <td align="left"><nobr><a href="relnotes.html"><img src="prev.png"border=0 alt="[Prev]"></a> </nobr></td><td align="center" width="99%"><a href="mhonarc.html"><img src="up.png" border=0 alt="[TOC]"></a><a href="faq/faq.html"><img src="faq.png" border=0 alt="[FAQ]"></a><a href="app-bugs.html"><img src="bug.png" border=0 alt="[Bugs]"></a><a href="http://www.mhonarc.org/"><img src="home.png" border=0 alt="[Home]"></a></td><td align="right"><nobr> <a href="quickstart.html"><img src="next.png" border=0 alt="[Next]"></a></nobr></td></tr></table> | |
16 | <!--X-NavButtons-End--> | |
17 | <HR> | |
18 | ||
19 | <H1><a name="installation">Installation</a></H1> | |
20 | ||
21 | <p>The following section describes how to install MHonArc on your | |
22 | system. | |
23 | </p> | |
24 | <table border=0 cellpadding=4> | |
25 | <tr valign=top> | |
26 | <td><strong>NOTE</strong></td> | |
27 | <td><p>Make sure to read the | |
28 | <a href="relnotes.html">release notes</a> before installing MHonArc, | |
29 | especially if you are upgrading from a previous release. If you | |
30 | are reading the text version of this installation document, a text | |
31 | version of the release notes is contained in the file <tt>RELNOTES</tt> | |
32 | contained within the root of the MHonArc distribution. | |
33 | </p> | |
34 | </td> | |
35 | </tr> | |
36 | </table> | |
37 | ||
38 | ||
39 | <!--X-TOC-Start--> | |
40 | <ul> | |
41 | <li><a href="#sysreqs">System Requirements</a> | |
42 | <li><a href="#download">Downloading MHonArc</a> | |
43 | <li><a href="#extraction">Extracting the MHonArc Distribution</a> | |
44 | <li><a href="#installingviainstallme">Installing with <tt>install.me</tt></a> | |
45 | <ul> | |
46 | <li><small><a href="#installmenotes"><tt>install.me</tt> Notes</a></small> | |
47 | </ul> | |
48 | <li><a href="#p5install">The Perl 5 Way</a> | |
49 | <li><a href="#win32">Win32 Notes</a> | |
50 | <li><a href="#altos">Alternate Operating Systems</a> | |
51 | <li><a href="#manual">Manual Installation</a> | |
52 | <li><a href="#postinstall">Post Installation Configuration</a> | |
53 | <ul> | |
54 | <li><small><a href="#siterc">Default Resource File</a></small> | |
55 | <li><small><a href="#sitelib">Site Initialization Library</a></small> | |
56 | </ul> | |
57 | <li><a href="#rcfileedit">Resource File Editing</a> | |
58 | </ul> | |
59 | <!--X-TOC-End--> | |
60 | ||
61 | <!-- *************************************************************** --> | |
62 | <hr> | |
63 | <h2><a name="sysreqs">System Requirements</a></h2> | |
64 | ||
65 | <p>The following is required inorder to use MHonArc: | |
66 | </p> | |
67 | <ul> | |
68 | <li><p>Perl 5 is installed. If you do not have Perl 5, goto | |
69 | <a href="http://language.perl.com/" | |
70 | ><http://language.perl.com/></a> for download information. | |
71 | </p> | |
72 | </li> | |
73 | <li><p><b>Getopt::Long</b> and <b>Time::Local</b> modules are installed. | |
74 | These modules are part of the standard Perl distribution. | |
75 | </p> | |
76 | </li> | |
77 | <li><p>The following modules are optional: | |
78 | </p> | |
79 | <ul> | |
80 | <li><p><b>Digest::MD5</b>: Used for creating IDs for messages without | |
81 | message-ids. This module helps MHonArc detect already | |
82 | archived messages for messages without message-ids. | |
83 | </p> | |
84 | </li> | |
85 | <li><p><b>Fcntl</b>, <b>Symbol</b>: Used for flock() based archive locking | |
86 | (if specified by the user). See <a href="resources/lockmethod.html">LOCKMETHOD</a> | |
87 | resource for more information. | |
88 | </p> | |
89 | </li> | |
90 | </ul> | |
91 | <p>MHonArc will still function if the above listed modules are | |
92 | not available. | |
93 | </p> | |
94 | </li> | |
95 | </ul> | |
96 | ||
97 | <table border=0 cellpadding=4> | |
98 | <tr valign=top> | |
99 | <td><strong>NOTE</strong></td> | |
100 | <td><p>The MHonArc installation program will check that required modules | |
101 | are available before installing MHonArc on your system. | |
102 | </p> | |
103 | </td> | |
104 | </tr> | |
105 | </table> | |
106 | ||
107 | <!-- *************************************************************** --> | |
108 | <hr> | |
109 | <h2><a name="download">Downloading MHonArc</a></h2> | |
110 | ||
111 | <p>The homepage for MHonArc is | |
112 | <A HREF="http://www.mhonarc.org/" | |
113 | ><http://www.mhonarc.org/></A>. The homepage | |
114 | list various sites that you can download MHonArc. If you are | |
115 | familiar with | |
116 | <a href="http://www.perl.com/CPAN/">Comprehensive Perl Archive Network | |
117 | (CPAN)</a>, MHonArc can be downloaded from | |
118 | <a href="http://www.perl.com/CPAN/authors/id/EHOOD/" | |
119 | ><http://www.perl.com/CPAN/authors/id/EHOOD/></a>. | |
120 | </p> | |
121 | ||
122 | <p>MHonArc is distributed in the following formats: | |
123 | </p> | |
124 | <ul> | |
125 | <li><b>tar-bz2</b>: <tt>MHonArc<var>X.X.X</var>.tar.bz2</tt> | |
126 | </li> | |
127 | <li><b>tar-gzip</b>: <tt>MHonArc<var>X.X.X</var>.tar.gz</tt> | |
128 | </li> | |
129 | <li><b>zip</b>: <tt>MHonArc<var>X.X.X</var>.zip</tt> | |
130 | </li> | |
131 | </ul> | |
132 | <p>where <tt><var>X.X.X</var></tt> represents the version number. | |
133 | </p> | |
134 | <p>Alternate distribution formats for MHonArc may be available, like | |
135 | Linux RPM. Alternate distribution formats are not covered in this | |
136 | document. | |
137 | </p> | |
138 | ||
139 | <!-- *************************************************************** --> | |
140 | <hr> | |
141 | <h2><a name="extraction">Extracting the MHonArc Distribution</a></h2> | |
142 | ||
143 | <p>After downloading MHonArc, it is best to move the file to a | |
144 | temporary location for extraction. To extract the distribution | |
145 | under Unix-like systems, use one of the following commands based upon the | |
146 | distribution format you downloaded: | |
147 | </p> | |
148 | <dl> | |
149 | <dt><b>tar-bz2</b></dt> | |
150 | <dd><pre> | |
151 | shell> <b>bzip2 -dc MHonArc<var>X.X.X</var>.tar.bz2 | tar xvf -</b></pre> | |
152 | <dt><b>tar-gzip</b></dt> | |
153 | <dd><pre> | |
154 | shell> <b>gzip -dc MHonArc<var>X.X.X</var>.tar.gz | tar xvf -</b></pre> | |
155 | </dd> | |
156 | <dt><b>zip</b></dt> | |
157 | <dd><pre> | |
158 | shell> <b>unzip MHonArc<var>X.X.X</var>.zip</b></pre> | |
159 | </dd> | |
160 | </dl> | |
161 | ||
162 | <p>For Win32 systems, you can use a program like <em>WinZip</em> to | |
163 | extract the tar-gzip or zip formats. If using | |
164 | <em><a href="http://www.cygwin.com/">Cygwin</a></em>, you can use | |
165 | the Unix-based extraction methods. | |
166 | </p> | |
167 | ||
168 | <p>After extraction, the subdirectory <tt>MHonArc<var>X.X.X</var></tt> will | |
169 | have been created containing all the files comprising MHonArc. | |
170 | </p> | |
171 | <table border=0 cellpadding=4> | |
172 | <tr valign=top> | |
173 | <td><strong>IMPORTANT</strong></td> | |
174 | <td><p>Please read the <a href="relnotes.html">release notes</a> | |
175 | before continuing for any news about compatibility | |
176 | with previous versions and/or important usage information. | |
177 | </p> | |
178 | </td> | |
179 | </tr> | |
180 | </table> | |
181 | <p>You | |
182 | will now want to change your current directory to <tt>MHonArc<var>X.X.X</var></tt> | |
183 | for the <a href="#installingfiles">next step</a>. | |
184 | </p> | |
185 | ||
186 | <!-- *************************************************************** --> | |
187 | <hr> | |
188 | <h2><a name="installingviainstallme">Installing with <tt>install.me</tt></a></h2> | |
189 | ||
190 | <p>Provided in the MHonArc distribution is a Perl program, | |
191 | <b><tt>install.me</tt></b> | |
192 | that will install MHonArc on your system. To run the program, type | |
193 | the following at your shell prompt: | |
194 | </p> | |
195 | <pre> | |
196 | shell> <b>perl install.me</b> | |
197 | </pre> | |
198 | <table border=0 cellpadding=4> | |
199 | <tr valign=top> | |
200 | <td><strong>IMPORTANT</strong></td> | |
201 | <td><p>You must be in the same directory as the <b><tt>install.me</tt></b> | |
202 | program when you run it. | |
203 | </p> | |
204 | </td> | |
205 | </tr> | |
206 | </table> | |
207 | ||
208 | <p>The installation program will ask you a series of questions on where | |
209 | the perl executable is and where to put MHonArc files. Just hit | |
210 | <CR> to accept the default values listed in ()'s. Note, the default | |
211 | values are determined by the configuration of perl on your system. | |
212 | If you choose the defaults, you may need to possess root/admin privileges | |
213 | to have a successful install. | |
214 | </p> | |
215 | ||
216 | <p><b><tt>install.me</tt></b> can take several options on the | |
217 | command-line to affect what is done during installation. The following | |
218 | is the list of options available: | |
219 | </p> | |
220 | <pre> | |
221 | -afs : Skip permission checks (useful if AFS) | |
222 | -batch : Run in batch mode (do not ask questions) | |
223 | -binpath <path> : Directory path to install programs/scripts | |
224 | -docpath <path> : Directory path to install documentation | |
225 | -help : A message summarizing options available | |
226 | -libpath <path> : Directory path to install library files | |
227 | -filelist <file> : List of files to install (def="FILELIST") | |
228 | -manpath <path> : Directory path to manpages | |
229 | -nobin : Do not install programs | |
230 | -nodep : Skip module dependency check | |
231 | -nodoc : Do not install documentation | |
232 | -nolib : Do not install library files | |
233 | -noman : Do not install manpages | |
234 | -perl <pathname> : Pathname of perl interpreter | |
235 | -prefix <path> : Set prefix for installation directories | |
236 | </pre> | |
237 | ||
238 | <p>For example, if you do not want to install the documentation, do | |
239 | the following: | |
240 | </p> | |
241 | <pre> | |
242 | shell> <b>perl install.me -nodoc</b> | |
243 | </pre> | |
244 | ||
245 | <p>Later on, if you decide you want to install the documentation, but | |
246 | not re-install the other files, do the following: | |
247 | </p> | |
248 | <pre> | |
249 | shell> <b>perl install.me -nobin -nolib -noman</b> | |
250 | </pre> | |
251 | ||
252 | <p>If you want to install files relative to your home directory, do the | |
253 | following: | |
254 | </p> | |
255 | <pre> | |
256 | shell> <b>perl install.me -prefix $HOME</b> | |
257 | </pre> | |
258 | ||
259 | <h3><a name="installmenotes"><tt>install.me</tt> Notes</a></h3> | |
260 | <ul> | |
261 | <li><p>The "#!" line in the installed programs are set to point to | |
262 | the perl executable specified in the installation process. | |
263 | This is convienence for those using systems that support the | |
264 | "#!" notation. | |
265 | </p> | |
266 | </li> | |
267 | <li><p>The installation lib directory is added to each program's | |
268 | search path so each program can find the libaries needed for | |
269 | proper execution. Therefore, you should <b>NOT</b> have to set your | |
270 | PERL5LIB environment variable if you install the library files | |
271 | in a location not in the default perl library search path. | |
272 | </p> | |
273 | </li> | |
274 | <li><p>If you specify paths that do not exist, the <tt>install.me</tt> | |
275 | program will create the paths for you. If running in | |
276 | interactive mode, you will be prompted before each path | |
277 | is created. | |
278 | </p> | |
279 | </li> | |
280 | <li><p><tt>install.me</tt> supports environment variable interpolation in | |
281 | pathnames specified during interactive installation. | |
282 | For example, if you want to install the program files into | |
283 | your local bin directory, you can enter the following when | |
284 | prompted for the location to install executables: <tt>$HOME/bin</tt>. | |
285 | Also, if the '~' (tilde) character is the first character of the | |
286 | pathname specified, it will be expanded to the value of the | |
287 | HOME environment variable. Therefore, the following are | |
288 | equivalent: <tt>$HOME/bin</tt> and <tt>~/bin</tt>. | |
289 | </p> | |
290 | </li> | |
291 | <li><p>The <b><tt>-afs</tt></b> option should only be needed | |
292 | if installing MHonArc onto AFS and using an older version of Perl 5. | |
293 | It should not be needed for Perl 5.005 or later. | |
294 | </p> | |
295 | </li> | |
296 | <li><p>If you want to abort the installation, just enter the | |
297 | termination character. For Unix systems, it is normally | |
298 | Ctrl-C; for Win32 systems, it is normally Ctrl-Z. | |
299 | </p> | |
300 | </li> | |
301 | </ul> | |
302 | ||
303 | <!-- *************************************************************** --> | |
304 | <hr> | |
305 | <h2><a name="p5install">The Perl 5 Way</a></h2> | |
306 | ||
307 | <p>Of course, you can install MHonArc the standard way under Perl 5: | |
308 | </p> | |
309 | <pre> | |
310 | shell> perl Makefile.PL | |
311 | shell> make | |
312 | shell> make install | |
313 | </pre> | |
314 | <p>If you want to install in a specific directory, try: | |
315 | </p> | |
316 | <pre> | |
317 | shell> perl Makefile.PL PREFIX=/tmp/myperl5 | |
318 | shell> make | |
319 | shell> make install | |
320 | </pre> | |
321 | ||
322 | <table border=0 cellpadding=4> | |
323 | <tr valign=top> | |
324 | <td><strong>NOTE</strong></td> | |
325 | <td><p><b><tt>install.me</tt></b> is actually called "behind the scenes" | |
326 | in batch mode to install the files. | |
327 | </p> | |
328 | </td> | |
329 | </tr> | |
330 | </table> | |
331 | ||
332 | ||
333 | <!-- *************************************************************** --> | |
334 | <hr> | |
335 | <h2><a name="win32">Win32 Notes</a></h2> | |
336 | <ul> | |
337 | <li><p>The main programs will automatically be converted to DOS batch | |
338 | files. Hence, if the path location of the main programs is | |
339 | in your PATH, you should be able to invoke them like any other | |
340 | program. Note, the path to the perl executable must be in | |
341 | your PATH, also. | |
342 | </p> | |
343 | </li> | |
344 | <li><p>The main programs will also be copied to "<tt>.pl</tt>" files. | |
345 | Therefore, if you have <tt>.pl</tt> associated with Perl in the registry, you | |
346 | can invoke the programs directly (if the path location of the | |
347 | main programs are in your search path). For example: | |
348 | </p><pre> | |
349 | shell> <b>mhonarc.pl ...</b> | |
350 | </pre> | |
351 | <p>This is known to work under WinNT and under the Cygwin bash shell. | |
352 | </p> | |
353 | <p>This is better than going though the batch file mechanism since | |
354 | I/O redirection does not work when invoking a batch file. | |
355 | </p> | |
356 | </li> | |
357 | <li><p>In the <b><tt>logo</tt></b> directory of the distribution is a BMP file | |
358 | <b><tt>mhaicon.bmp</tt></b>. You can copy the image into your Windows Icon | |
359 | directory. Then through the file types editor of the file | |
360 | explorer, you can specify <b><tt>mhaicon.bmp</tt></b> as the icon for MHonArc | |
361 | resource (<b><tt>.mrc</tt></b>) files. | |
362 | </p> | |
363 | <p>This method of associating the icon to MHonArc resource files | |
364 | is known to work with Win9x systems. | |
365 | </li> | |
366 | </ul> | |
367 | ||
368 | <!-- *************************************************************** --> | |
369 | <hr> | |
370 | <h2><a name="altos">Alternate Operating Systems</a></h2> | |
371 | ||
372 | <p>In many cases, the <tt>install.me</tt> program will work for other operating | |
373 | systems. Please contact the author on any success stories for | |
374 | other operating systems, and please send any patches, if required. | |
375 | </p> | |
376 | ||
377 | <!-- *************************************************************** --> | |
378 | <hr> | |
379 | <h2><a name="manual">Manual Installation</a></h2> | |
380 | ||
381 | <p>If <tt>install.me</tt> will not work properly for your system, here are the | |
382 | steps to install MHonArc manually: | |
383 | </p> | |
384 | <ul> | |
385 | ||
386 | <li><p>Copy files in the <tt>lib</tt> directory to the | |
387 | library location you desire. | |
388 | </p> | |
389 | </li> | |
390 | <li><p>Copy the program files to the location you want them | |
391 | installed. After copying, you must edit the each file | |
392 | as follows: | |
393 | </p> | |
394 | <ul> | |
395 | <li><p>Edit the "<tt>#!/...</tt>" line (the first line of each file) | |
396 | to be the complete pathname of your perl interpreter. | |
397 | Note, this step is only required for systems (Unix) | |
398 | that support "<tt>#!</tt>". | |
399 | </p> | |
400 | </li> | |
401 | <li><p>Add a new line right after the "<tt>#!/...</tt>" line to | |
402 | contain the following: | |
403 | </p><pre> | |
404 | use lib '/path/to/lib/files'; | |
405 | </pre> | |
406 | <p>where "<tt>/path/to/lib/files/</tt>" is the path to where | |
407 | copied the library files to. | |
408 | </p> | |
409 | <p>Note, if the location you copied the libraries are | |
410 | already part of Perl's standard library search path, | |
411 | you do not need to add the "use lib" statement. | |
412 | </p> | |
413 | </li> | |
414 | </ul> | |
415 | </li> | |
416 | </ul> | |
417 | ||
418 | <!-- *************************************************************** --> | |
419 | <hr> | |
420 | <h2><a name="postinstall">Post Installation Configuration</a></h2> | |
421 | ||
422 | <p>After installation, you may want to do some site-specific | |
423 | configuration. | |
424 | </p> | |
425 | ||
426 | <h3><a name="siterc">Default Resource File</a></h3> | |
427 | ||
428 | <p>You have the ability to create a default | |
429 | <a href="resources/rcfile.html">resource file</a> | |
430 | to make site-wide defaults for MHonArc. See | |
431 | the <a href="resources/defrcfile.html">DEFRCFILE</a> resource | |
432 | on valid pathname locations for the default resource file. | |
433 | For more information on what can be put in | |
434 | a resource file, see the | |
435 | <a href="resources.html">Resources</a> section. | |
436 | </p> | |
437 | <table border=0 cellpadding=4> | |
438 | <tr valign=top> | |
439 | <td><strong>NOTE</strong></td> | |
440 | <td><p>It is advisable to create some local documentation for | |
441 | users describing | |
442 | any settings you place in the site-wide resource file. | |
443 | This will avoid confusion if site settings vary from default settings | |
444 | described in the documentation, and it will help avoid invalid bug | |
445 | reports. | |
446 | </p> | |
447 | </td> | |
448 | </tr> | |
449 | </table> | |
450 | ||
451 | <h3><a name="sitelib">Site Initialization Library</a></h3> | |
452 | ||
453 | <p>If you do not know Perl, ignore this section. | |
454 | </p> | |
455 | <p>When MHonArc opens an archive for processing, MHonArc | |
456 | will attempt to execute the instructions in the file | |
457 | <b><tt>mhasiteinit.pl</tt></b>. This file allows you | |
458 | to make site customizations not possible through a | |
459 | <a href="resources/defrcfile.html">default resource file</a>. | |
460 | <b><tt>mhasiteinit.pl</tt></b> should be placed in the | |
461 | MHonArc library directory as specified during installation. | |
462 | A sample <b><tt>mhasiteinit.pl</tt></b> file is provied in the | |
463 | <b><tt>examples</tt></b> directory of the distribution to get you | |
464 | started, which includes comments on some of the things you | |
465 | can do with <tt>mhasiteinit.pl</tt>. | |
466 | </p> | |
467 | ||
468 | <!-- *************************************************************** --> | |
469 | <hr> | |
470 | <h2><a name="rcfileedit">Resource File Editing</a></h2> | |
471 | ||
472 | <p>If you are a Vim user, | |
473 | <a href="http://www.vim.org/"><http://www.vim.org/></a>, a syntax file | |
474 | for MHonArc resource files is included in the examples directory: | |
475 | <b><tt>mhonarc.vim</tt></b>. | |
476 | Vim is known to run on a variety of operating systems, | |
477 | and is free software. | |
478 | </p> | |
479 | ||
480 | <p>To use <tt>mhonarc.vim</tt>, copy <tt>mhonarc.vim</tt> to an | |
481 | appropriate location and | |
482 | add something like the following to your <tt>.vimrc</tt> file: | |
483 | </p> | |
484 | <pre> | |
485 | au BufNewFile,BufRead *.mrc so $HOME/share/vim/syntax/mhonarc.vim | |
486 | </pre> | |
487 | <p>Of course, change the pathname to <tt>mhonarc.vim</tt> to wherever | |
488 | you copied it to. | |
489 | </p> | |
490 | ||
491 | <p>Now, any file with <tt>.mrc</tt> extension will put Vim into | |
492 | MHonArc resource file highlighting mode. The mode is best used with | |
493 | color-capable terminals. | |
494 | </p> | |
495 | ||
496 | <HR> | |
497 | <!--X-NavButtons-Start--> | |
498 | <table width="100%"> | |
499 | <tr valign="top"> | |
500 | <td align="left"><nobr><a href="relnotes.html"><img src="prev.png"border=0 alt="[Prev]"></a> </nobr></td><td align="center" width="99%"><a href="mhonarc.html"><img src="up.png" border=0 alt="[TOC]"></a><a href="faq/faq.html"><img src="faq.png" border=0 alt="[FAQ]"></a><a href="app-bugs.html"><img src="bug.png" border=0 alt="[Bugs]"></a><a href="http://www.mhonarc.org/"><img src="home.png" border=0 alt="[Home]"></a></td><td align="right"><nobr> <a href="quickstart.html"><img src="next.png" border=0 alt="[Next]"></a></nobr></td></tr></table> | |
501 | <!--X-NavButtons-End--> | |
502 | ||
503 | <!-- *************************************************************** --> | |
504 | <hr> | |
505 | <address> | |
506 | $Date: 2002/05/27 20:07:10 $ <br> | |
507 | <img align="top" src="monicon.png" alt=""> | |
508 | <a href="http://www.mhonarc.org/"><strong>MHonArc</strong></a><br> | |
509 | Copyright © 1997-2002, <a href="http://www.mhonarc.org/~ehood/" | |
510 | >Earl Hood</a>, <a href="mailto:mhonarc@mhonarc.org" | |
511 | >mhonarc@mhonarc.org</a><br> | |
512 | </address> | |
513 | ||
514 | </BODY> | |
515 | </HTML> |