Installation
============
If you are upgrading from older versions of LinkChecker you should
also read the upgrading documentation stored in UPGRADING.txt.


Setup for Windows
-----------------
Execute ``LinkChecker-x.y.exe`` and follow the instructions.


Setup for Mac OS X
------------------
Double click ``LinkChecker-x.y.dmg`` and drop the LinkChecker application
in your programs folder


Setup for Unix/Linux
--------------------
First, install the required software.

1. You need a standard GNU development environment with
   
   - C compiler (for example the GNU C Compiler gcc)
     
     Depending on your distribution, several development packages
     might be needed to provide a fully functional C development
     environment.
   
   Note for developers: if you want to regenerate the po/linkchecker.pot
   template from the source files, you will need xgettext with Python
   support. This is available in gettext >= 0.12.

2. Python >= 2.6 from http://www.python.org/
   
   Be sure to also have installed the included distutils module.
   On most distributions, the distutils module is included in
   an extra ``python-dev`` package.

3. Qt development tools
   
   The binary "qcollectiongenerator" is used to generate the
   documentation files.
   On Debian or Ubuntu systems, install the package qt4-dev-tools.

4. *Optional, for bash-completion:*
   optcomplete Python module from http://furius.ca/optcomplete/

5. *Optional, for HTML/CSS syntax checks:*
   HTML tidy from http://utidylib.berlios.de/
   cssutils from http://cthedot.de/cssutils/

6. *Optional, for displaying country codes:*
   GeoIP from http://www.maxmind.com/app/python

7. *Optional, used for Virus checking:*
   ClamAv from http://www.clamav.net/

8. *Optional, used for login form submission:*
   Twill from http://twill.idyll.org/

9. *Optional, for Mozilla Bookmark parsing:*
   Python Sqlite from https://code.google.com/p/pysqlite/

10. *Optional, for GNOME proxy setting parsing:*
    Python Gtk from http://www.pygtk.org/downloads.html

11. *Optional, to run the CGI web interface:*
    Apache from http://httpd.apache.org/


Now install the application.

1. Generate Qt documentation
   
   Run ``make -C doc/html`` to generate the Qt help file.

2. Compile Python modules
   
   Run ``python setup.py sdist --manifest-only`` to create the MANIFEST
   file.
   Run ``python setup.py build`` to compile the Python files.
   For help about the setup.py script options, run
   ``python setup.py --help``.
   The CC environment variable is checked before compilation, so you can
   change the default C compiler with ``export CC=myccompiler``.

3.
   a) Installation as root
      
      Run ``sudo python setup.py install`` to install LinkChecker.
   
   b) Installation as a normal user
      
      Run ``python setup.py install --home $HOME``. Note that you have
      to adjust your PATH and PYTHONPATH environment variables, eg. by
      adding the commands ``export PYTHONPATH=$HOME/lib/python`` and
      ``export PATH=$PATH:$HOME/bin`` to your shell configuration
      file.
      
      For more information look at the `Modifying Python's search path`_
      documentation.
      
      .. _Modifying Python's search path:
         http://docs.python.org/inst/search-path.html#SECTION000410000000000000000


After installation
------------------
LinkChecker is now installed. Have fun!


(Fast)CGI web interface
-----------------------
The included CGI scripts can run LinkChecker with a nice graphical web
interface.
You can use and adjust the example HTML files in the lconline directory
to run the script.

0. Note that running LinkChecker requires CPU and memory resources.
   Allowing a CGI script to execute such a program for possibly a
   large number of users might deplete those resources.
   Be sure to only allow access from trusted sites to this script.
   
1. Choose a CGI script. The simplest is lc.cgi and you need a web server
   with CGI support.
   The script lc.fcgi (I tested this a while ago) needs a web server
   with FastCGI support.

2. Copy the script of your choice in the CGI directory.

3. Adjust the "action=..." parameter in lconline/lc_cgi.html
   to point to your CGI script.

4. Load the lconline/index.html file, enter an URL and click on the
   check button.

5. If something goes wrong, check the following:
   
   a) look in the error log of your web server
   b) be sure that you have enabled CGI support in your web server
      do this by running other CGI scripts which you know are
      working
   c) try to run the lc.cgi script by hand
   d) try the testit() function in the lc.cgi script
