miau - installing miau for dummies (rev 2b)

This is an early version of this guide and written miau 0.5.2 in mind.. It probably contains several grave errors and you probably should not be reading this. If you decide to continue, well, all feedback is greatly appreciated.

If INSTALL file (provided in all miau distributions) proved to be too difficult to comprehend or if you don't feel too confident in installing miau, this guide is designed for you. This step-by-step guide shows you how to get, unpack, compile and install miau on most platforms.

To get miau up and running, you need to

• Get the sources
• Unpack the sources
• Choose compile options
• Compile
• Install
• Configure miau
• (Set up crontab)
• (Clean up)

None of the steps should be too difficult so don't worry - we'll get miau up and running. And if something goes wrong, you can always ask for help and/or post a bug report.

There's also a short guide on how to upgrade your version of miau.

• Important things

  When you need to pay special attention in something, the important part is written like this.

• Filenames and other things on computer screen

  Filenames, names of programs and other things you're going to see on computer (like --enable-local) are written with monospace font like miau-0.5.2.tar.gz. You may already have noticed this way of marking files in the introduction where file INSTALL was mentioned.

• Input and output

  Whenever you need to do some typing or there's something important on the screen to see, it's marked like this:

  $ ./configure --enable-local
  checking for a BSD-compatible install... /usr/bin/install -c
  checking whether build environment is sane... yes
  checking whether make sets ${MAKE}... yes
  ...
  ...
  ...
  config.status: creating config.h
  config.status: executing depfiles commands
  Now type 'make' to compile.
  $
  

  Everything that's after leading "$" is something you need to type - the other lines are what computer says. Don't worry if the output isn't exactly identical - that's perfectly normal. Also notice that

  ...
  ...
  ...
  

  means that there's supposed to be more output but it's been omitted here.

If you're planning to run miau on remote computer, you probably want to get sources directly to that computer. If you're any familiar with remote computer's command line, you should be fine. To get the sources directly, remote system must have necessary software installed (wget, lynx, links, etc.). However, if you're more comfortable using your favorite browser to get the sources, you need to be able to transfer files to the remote host. Both ways are equally good so choose it yourself.

Whatever you're using your browser or command line, first you need to locate the sources from sourceforge.net. Go to project filelist, click the uppermost miau-0.5.2.tar.gz (where 0.5.2 represents the version of miau) and choose the nearest mirror (like Prague, Czech Republic). After selecting the mirror, the download should start automatically. However, if you're going to use wget or other command line program to get the sources, cancel the download and get the URL instead. URL you're looking for should be marked clearly above "You are using mirror" -text and it should look like http://cesnet.dl.sourceforge.net/sourceforge/miau/miau-0.5.2.tar.gz. Remember this URL, you'll need it later.

If you don't know if wget, lynx or links is installed, it doesn't do any harm to try them. Just try each way. Before proceeding, make sure you're in your home directory by doing the following or further instructions may not work.

$ cd
$

To get the sources with wget, you need the URL we resolved earlier. Try the following, where http://cesnet.dl.sourceforge.net/sourceforge/miau/miau-0.5.2.tar.gz is replaced with your URL.

$ wget http://cesnet.dl.sourceforge.net/sourceforge/miau/miau-0.5.2.tar.gz
--11:19:02--  http://cesnet.dl.sourceforge.net/sourceforge/miau/miau-0.5.2.tar.gz
           => `miau-0.5.2.tar.gz'
Resolving cesnet.dl.sourceforge.net... 195.113.161.88
Connecting to cesnet.dl.sourceforge.net[195.113.161.88]:80... connected.
HTTP request sent, awaiting response... 200 OK
Length: 201,744 [application/x-gzip]

100%[====================================>] 201,744       64.75K/s    ETA 00:00

11:19:05 (64.61 KB/s) - `miau-0.5.2.tar.gz' saved [201744/201744]
$

If you saw something like

$ wget http://cesnet.dl.sourceforge.net/sourceforge/miau/miau-0.5.2.tar.gz
bash: wget: command not found
$

instead, wget is not installed (or isn't in command path). Please try one of the other methods.

To download the sources with lynx, you need to know the URL we resolved earlier (actually you wouldn't need your browser at all, but explaining it this way is lot easier). Try the following, where http://cesnet.dl.sourceforge.net/sourceforge/miau/miau-0.5.2.tar.gz is replaced with your URL.

$ lynx http://cesnet.dl.sourceforge.net/sourceforge/miau/miau-0.5.2.tar.gz

If lynx is not installed (or isn't in command path), you should see something like

$ lynx http://cesnet.dl.sourceforge.net/sourceforge/miau/miau-0.5.2.tar.gz
bash: lynx: command not found
$

If lynx is installed and it allows you to download files, it should ask you what to do with the file.

application/x-gzip  D)ownload, or C)ancel

Press "D" to download the file. When done, use keyboard (arrow keys and enter) to choose "Save to disk". At the bottom of the screen, lynx should now ask where to save the file

Enter a filename: miau-0.5.2.tar.gz

Just press enter. After this, press ctrl-c to return to command line.

To download the sources with links, you need to know the URL we resolved earlier (actually you wouldn't need your browser at all, but explaining it this way is lot easier). Try the following where http://cesnet.dl.sourceforge.net/sourceforge/miau/miau-0.5.2.tar.gz is replaced with your URL.

$ links http://cesnet.dl.sourceforge.net/sourceforge/miau/miau-0.5.2.tar.gz

If links is not installed (or not in command path), you should see something like

$ links http://cesnet.dl.sourceforge.net/sourceforge/miau/miau-0.5.2.tar.gz
bash: links: command not found
$

If links is installed, links should now ask what to do with the file. Choose Save by pressing enter (if Save isn't selected, use cursor keys to select it). Next links should prompt where to save the file. Just press enter. When file is downloaded, you should see an empty screen. Now press ctrl-c to return to command line.

Find the sources as described earlier in Finding the sources from sourceforget.net -section of this guide and download the sources. If you're going to install miau on remote computer, you need to copy downloaded file to that computer. I'm afraid I cannot help you with this so you need to figure this out by yourself. If you're stuck, you should contact your service provider. Anyway, copy the source package to your home directory (usually the default directory after you connect the remote computer).

Once you got the source, unpack it.

$ gzip -cd miau-0.5.2.tar.gz | tar -xf -
$

where 0.5.2 is replaced by version of miau you're installing. If computer didn't say a thing, everything went fine. If computer said anything, something didn't go as expected. In this case, read the message carefully, it should tell what was wrong. If you see something like

$ gzip -cd miau-0.5.2.tar.gz | tar -xf -
tar: Archive contains future timestamp 2004-04-01 01:25:39
$

you don't need to worry.

If you got something like

$ gzip -cd miau-0.5.2.tar.gz | tar -xf -
$ gzip: miau-0.5.2.tar.gz: No such file or directory
$

the sources are not in the root of your home directory. If you're sure you already downloaded the sources (and copied the package in your home directory, if you downloaded the sources with your local computer), you can try to locate the sources with find.

$ find ~ -name 'miau-*.tar.gz'
/home/wind/somewhere/else/miau-0.5.2.tar.gz
$

This means the sources are in /home/wind/somewhere/else instead of /home/wind. You can move the package in your home directory with mv.

$ mv /home/wind/somewhere/else/miau-0.5.2.tar.gz ~
$

If find didn't find anything, this guide can't help you any further than to suggest going back to getting the sources. Sorry.

$ find ~ -name 'miau-*.tar.gz'
$

Before compiling miau you will need to choose what features to compile into miau. First you need to go to the source directory:

$ cd miau-0.5.2
$

where 0.5.2 is the version of miau you're about to install. This version is the same as in source package filename.

Once you're in the source directory, do

$ ./configure --help
`configure' configures miau 0.5.2 to adapt to many kinds of systems.

Usage: ./configure [OPTION]... [VAR=VALUE]...
...
...
...
Optional Features:
  --disable-FEATURE       do not include FEATURE (same as --enable-FEATURE=no)
  --enable-FEATURE[=ARG]  include FEATURE [ARG=yes]
  --enable-local          install miau locally, not system-wide
  --enable-ipv6           enable ipv6-support
  --enable-dccbounce      enable DCC-bouncing capability
  --enable-automode       enable automode -capability
...
...
...
$

Now, concentrate on Optional Features. As configure told you, to enable a feature, you need to give configure corresponding parameter. For example, if you want to use miau for logging channel messages only, give configure --enable-chanlog. Respectively, if you want to disable one of the features completely, use something like --disable-quicklog.

Note that you don't need to use features you decide to compile in, right now you're just enabling the features. Also note that you cannot use features that are disabled. That means, for example, if you've disabled quicklog here, it doesn't matter what you say in miau's configuration file, you cannot use quicklog-feature of miau without recompiling miau. If you like, you can enable all features. Note: If you enable IPv6, remote computer must support IPv6 or you cannot connect any server. If you're unsure about IPv6, either disable it or contact your service provider for answer.

One more thing: if you're installing miau from scratch, you most likely want to install miau locally, so consider using --enable-local switch. If you're upgrading local install, don't use this switch (and see selecting features for upgraded version for more information). This guide assumes you have done a local install. Once you've made up your mind, run configure with switches you just chose.

$ ./configure --enable-local --enable-automode
checking for a BSD-compatible install... /usr/bin/install -c
checking whether build environment is sane... yes
checking for gawk... gawk
checking whether make sets $(MAKE)... yes
...
...
...
config.status: creating config.h
config.status: executing depfiles commands
Now type 'make' to compile.
$

This would configure miau for compiling only automode-feature plus default features enabled. If you'd like to have miau writing channel log as well, just add --enable-chanlog switch - and if you don't care about quicklogging-feature, just add --disable-quicklog switch. I think you got the point.

You should now be set up to compile and install miau. If you didn't see Now type 'make' to compile, you should see an error message instead.

Compiling miau is easy, just type make:

$ make
make  all-recursive
make[1]: Entering directory `/home/wind/c/miau/old/miau-0.5.2'
Making all in src
...
...
...
make[2]: Entering directory `/home/wind/c/miau/old/miau-0.5.2'
make[2]: Leaving directory `/home/wind/c/miau/old/miau-0.5.2'
make[1]: Leaving directory `/home/wind/c/miau/old/miau-0.5.2'
$

If something went wrong, you should see an error message. If you saw something like

$ make
bash: make: command not found
$

you can try the following

$ gmake
...
...
...
$

If this doesn't help, you're out of luck: sorry, this guide can't help you.

Once you have succesfully compiled miau, it's time to install it by running make install.

$ make install
Making install in src
make[1]: Entering directory `/home/wind/c/miau/old/miau-0.5.2/src'
make[2]: Entering directory `/home/wind/c/miau/old/miau-0.5.2/src'
...
...
...
=============================================
Edit /home/wind/.miau/miaurc!
Additionally a /home/wind/miau/-dir has been
created and the miau-binary, documentation and
some other stuff has been put there.
=============================================
make[3]: Leaving directory `/home/wind/c/miau/old/miau-0.5.2'
make[2]: Leaving directory `/home/wind/c/miau/old/miau-0.5.2'
make[1]: Leaving directory `/home/wind/c/miau/old/miau-0.5.2'
$

Again, if make fails, try using gmake instead:

$ gmake
Making install in src
gmake[1]: Entering directory `/home/wind/c/miau/old/miau-0.5.2/src'
gmake[2]: Entering directory `/home/wind/c/miau/old/miau-0.5.2/src'
...
...
...
$

If you didn't see Edit /home/wind/.miau/miaurc!, something failed and you should read the output looking for error message (and perhaps contact the author).

If you're running miau 0.5.2 or older, you should also do the following

$ chmod 700 ~/.miau ~/miau
$ chmod 600 ~/.miau/* ~/miau/*
$

Neither of those commands should return anything. If they do, something isn't right.

To configure miau, you need to edit ~/.miau/miaurc. For more information about configuring miaurc, see the manual.

You can edit miaurc, which is a plain text file, with any editor you like. Most computers have at least one of vi, vim, nano, pico and emacs installed. See using editors if you don't know how to use these editors. Edit the file by doing

$ EDITOR ~/.miau/miaurc

where EDITOR is replaced with the editor of your choice. If you don't know which editor to try, I'd recommend trying nano, then emacs and finally vi. Personally I prefer vim, but many people find it confusing.

To edit miaurc on local computer, you first need to download miaurc, edit it, then upload it back. Whatever program you use to download miaurc, directory it resides in may not appear on filelist. In this case you need either to go to .miau directory by hand or by moving file to your home directory by hand by typing

$ mv ~/.miau/miaurc ~
$

Once you've edited miaurc upload it back to .miau or to your home directory if you couldn't get into .miau. If you had to upload miaurc into your home directory instead of directly into .miau, type

$ mv ~/miaurc ~/.miau
$

to move it back to .miau.

If your service provider allows it, cron can be set up to start miau automatically. With cron, you don't need to worry about restarting miau if the remote host is rebooted, miau crashed or you kill it by mistake.

Before you can set up crontab, you need to edit your miau-check.

$ EDITOR ~/miau/miau-check

Where EDITOR is replaced with your editor of choice, your editor will open up this file to be edited. See using editors if you don't know how edit the file. You must uncomment (remove # from the beginning of the line) line below "You must modify this if you have installed miau locally" so that part of the file reads

# You must modify this if you have installed miau locally:
MIAUBIN=$HOME/miau/miau

Once you're done, save the file and exit the editor.

Setting up a crontab is quite easy.

$ crontab -e

If you're allowed to have a crontab, this will open your crontab for editing in default editor. If you don't know how to use the editor, see using editor or if you don't know which editor just launched, see recognizing editor. Whatever editor is started, insert following line to an empty line in your crontab, save the changes and quit the editor. Note that crontab isn't supposed to caontan empty lines.

3,13,23,33,43,53 *  * * *  $HOME/miau/miau-check

If crontab -e returnes an error, you need to start miau manually (the output will differ a bit depending on version of miau and your configuration):

$ ~/miau/miau
-=============================================================-
 miau v0.5.3 "hairball" -- http://miau.sourceforge.net/
 Copyright (C) 2002-2004 Tommi Saviranta <tsaviran@cs.helsinki.fi>
        (C) 2002 Lee Hardy <lee@leeh.co.uk>
        (C) 1998-2002 Sebastian Kienzl <zap@riot.org>
-=============================================================-
     This program comes with ABSOLUTELY NO WARRANTY!
      This is free software, and you are welcome to
        redistribute it under certain conditions.
              For details, read 'COPYING'.
-=============================================================-

Apr 28 20:29:38 + Configuration read.
Apr 28 20:29:38 + Listening on port 45459.
Apr 28 20:29:38 + miau's nick is 'wind'.
Apr 28 20:29:38 + miau's forked. (pid 4572)
$

After you've compiled and installed miau, you may want to free up some disk space and delete the sources - you don't need them anymore. You can delete the sources by doing

$ cd
$ rm -rf miau-0.5.2
$

where 0.5.2 is the version of miau you installed.

To upgrade miau, you need to

• Get the sources
• Unpack the distribution
• Select features
• Compile miau
• Install new version
• (Review new miaurc)

If you've managed to install miau and have it running, upgrading should be a piece of cake. If you don't remember how to do things, just look back to respective chapters in this guide.

When you're upgrading miau you choose features to compile just like in Choosing features of miau chapter - the only difference is that you do not use --enable-local switch. Besides that, you should follow those instructions.

Replacing old version of miau with a new one differs a bit from installing miau from a scratch. When upgrading, you don't do make install but (still being in source directory)

$ rm -f ~/miau/miau
$ cp src/miau ~/miau
$

instead. Before installing new version you need to stop old miau or you may not be able to replace old version with a new one. You can stop old miau with /miau die command (or /quote miau die) with your IRC-client. Once you've replaced the old version, you can start the new one by running ~/miau/miau.

$ ~/miau/miau
-=============================================================-
 miau v0.5.3 "hairball" -- http://miau.sourceforge.net/
 Copyright (C) 2002-2004 Tommi Saviranta <tsaviran@cs.helsinki.fi>
        (C) 2002 Lee Hardy <lee@leeh.co.uk>
        (C) 1998-2002 Sebastian Kienzl <zap@riot.org>
-=============================================================-
     This program comes with ABSOLUTELY NO WARRANTY!
      This is free software, and you are welcome to
        redistribute it under certain conditions.
              For details, read 'COPYING'.
-=============================================================-

Apr 28 20:29:38 + Configuration read.
Apr 28 20:29:38 + Listening on port 45459.
Apr 28 20:29:38 + miau's nick is 'wind'.
Apr 28 20:29:38 + miau's forked. (pid 4572)
$

Unfortunately, sometimes syntax of miaurc changes. When this happens, it is mentioned in ChangeLog of miau. It is quite unlikely that syntax of miaurc does change, so usually you don't need to worry about this. However, if syntax have changed and you haven't updated your miaurc respectively, miau will refuse to start. See Configuring miau for more information.

nano and pico are almost identical in point of user's view so this section is for both of them. You can launch nano by typing

$ nano FILE

and pico by typing

$ pico FILE

if they're installed. Again, FILE is replaced with the filename you want to edit.

Editing files with nano and pico is very straightforward - just move cursor with cursor keys and edit file as usual, then save changes by pressing ctrl-o and pressing enter when editor asks for filename in the bottom of the screen

File Name to write : filename

After saving file, press ctrl-x to exit editor.

To start emacs, do

$ emacs FILE

where FILE is the file you want to edit.

Editing file with emacs is easy, just move cursor with cursor keys and edit file as usual, then save changes by pressing ctrl-x, then ctrl-s. Quit emacs by pressing ctrl-x, then ctrl-c.

When you start vi or vim by typing

$ vi FILE

or by

$ vim FILE

(where FILE is the file you're going to edit), first you want to go to edit mode by pressing i (there are other keys that enable editor mode as well). If cursor keys generate garbage instead of moving cursor, press esc once, then u to undo changes and move cursor in command mode instead. When you have moved cursor the place you want to edit, press i. After you're done with editing, press esc and then type :w, press enter and then :q and enter.

Recognizing the editor is easy if you know what you're looking for. If you haven't yet started the editor, you could try the following

$ echo $EDITOR
/usr/bin/vim
$

In this example, default editor was vim. If you got something like

$ echo $EDITOR

$

you need to find out which editor starts by default. Here's some suggestions on how to recognize nano, pico, vi(m) and emacs.

  GNU nano 1.2.3            File: /home/wind/.miau/miaurc                       

#
# miau 0.5.3 configuration file example
#

^G Get Help  ^O WriteOut  ^R Read File ^Y Prev Page ^K Cut Text  ^C Cur Pos
^X Exit      ^J Justify   ^W Where Is  ^V Next Page ^U UnCut Txt ^T To Spell

Notice GNU nano at the top of the screen.

   UW PICO(tm) 4.2                File: miaurc
   
#
# miau 0.5.3 configuration file example
#

^G Get Help  ^O WriteOut  ^R Read File ^Y Prev Pg   ^K Cut Text  ^C Cur Pos   
^X Exit      ^J Justify   ^W Where is  ^V Next Pg   ^U UnCut Text^T To Spell  

Notice UW PICO(tm) at the top of the screen.

File Edit Options Buffers Tools Insert Help                                     

#
# miau 0.5.3 configuration file example
#

--0-:---F1  miaurc            (Shell-script[bash])--L1--All---------------------
Indentation setup for shell type bash

"Menubar" at the top of the screen usually means you're running emacs.

#
# miau 0.5.3 configuration file example
#

"miaurc" 587 lines, 15895 characters

Notice the line at the bottom telling info about the file. vim is very similar to vi, but confusing the two doesn't matter right now: considering this guide, you can use vim like you would use vi.

#
# miau 0.5.3 configuration file example

"~/.miau/miaurc" 587L, 15895C                                 1,1           Top

Notice the line at the bottom telling info about the file. Most configurations of vim also tell cursor position (1,1 Top), but confusing vim with vi doesn't matter - vim is nothing but "Vi IMproved".