
********************************************************************************
* WARNING!                                                                     *
*                                                                              *
* This tool runs as the root user and installs packages on its own!            *
* Therefore it can do pretty much harm if it gets out of control.              *
* We have tried to make the script reasonably safe but there is no warranty.   *
* Use it at YOUR OWN RISK only, and only if you know what you are doing.       *
*                                                                              *
* Some setuid and setgid binaries may be generated and left behind after       *
* execution of the test suites (especially if certain tests fail).             *
* You should not install this package on production systems                    *
* or in situations where local users are not completely trusted.               *
*                                                                              *
* PLEASE DO NOT RUN IT ON A MACHINE THAT HOLDS IMPORTANT DATA, OR PROVIDES     *
* IMPORTANT SERVICES!                                                          *
********************************************************************************

---=< Prerequisites >=---

For running the script, you need to install the following tools:

* Perl
* rpm (should be always present for a LSB compliant distro)
* alien, if package manager on your distro isn't RPM.
* lsb_release (should be always present for a LSB compliant distro)
* standard Unix utils (grep, diff, etc.)
* curl or wget for downloading files.
* Xvfb (for LSB 3.0 and 3.1 tests), some fonts (for X11 tests)
* Some locales are required for libstdc++ test. That may turn into a problem for
  your distro. If that's the case, maybe the following solutions will help you:
  https://wiki.linuxfoundation.org/en/DistributionTestPrep#Locales_related_issues

All packages containing appropriate LSB tests will be downloaded automatically.

---=< Usage >=---

Some of the tests can temporarily put heavy load on the system (CPU, memory,
and disk), and various testing user accounts, servers and system config files
are created during the testing, causing temporary security holes.
All the changes should be reversed automatically after the testing is finished.

To start working with this tool using web-UI, run the following script from the
installation directory (/opt/lsb/test/manager by default):
# ./bin/dist-checker-start.pl [port]
It will launch a simple web-server, and then try to open the start page in 
a browser. The optional parameter 'port' allows to specify which port should be
used by the server. By default 8888 is taken.

Use the script ./bin/dist-checker-stop.pl if you want to shutdown the server.

You can also work with the Distribution Checker via a command-line interface.
Run
# /opt/lsb/test/manager/utils/dist-checker.pl --help
for a detailed list of options and their meanings.

---=< Troubleshooting >=---

* Some locales are required for libstdc++ test. That may turn into a problem for
  your distro. If that's the case, maybe the following solution will help you:
  https://wiki.linuxfoundation.org/en/DistributionTestPrep#Locales_related_issues

* In the case when the autotest couldn't find fonts, there is a workaround.
  First, find the font directory (see the files /etc/X11/xorg.conf and
  /etc/X11/fs/config). Also you may try the command 'find / -name 75dpi' to find
  all 75dpi font directories. Choose the appropriate font directory and make
  sure that the following subdirectories are present: 'misc', '75dpi', '100dpi'.

  Autotest tries to find these subdirectories in the following locations:
  /usr/X11R6/lib/X11/fonts/
  /usr/share/fonts/X11/
  /usr/share/X11/fonts/
  /usr/share/fonts/

  Create symlinks to the found directories (misc, 75dpi, 100dpi) into one of the
  directories listed above so that autotest could find them next time.

* If you have no 100dpi fonts installed, you should install them using the tools
  provided by your distro.

* If you want Distribution Checker to send results by e-mail, but it doesn't,
  then setup sendmail.

Error: Couldn't find a required tool: '<some tool>'
This error message occurs when you don't have some tool, which
Distribution Checker uses. You could try to install this tool.

Error: The ptyshell utility (...) doesn't exists or isn't executable.
'ptyshell' is a tool used by Distribution Checker to control the test
being executed. Distribution Checker tries to find ptyshell in
/opt/lsb/test/manager/ptyshell directory. Check that the file
/opt/lsb/test/manager/ptyshell/ptyshell exists and is executable by root.
If the file doesn't exists, it is most likely that the Distribution Checker
wasn't installed correctly, so you could reinstall it.

Error: The vsw4 test can't be run. Please install the Xvfb server first.
If this error appears despite you have already installed Xvfb, please restart
the Distribution Cheker's server so that the PATH variable was updated.

Error: No tests to run (use 'all' to run all available tests).
This error appears when no test suites are selected to be run, or all
selected test suites are unavailable for specified settings settings.
Use --list option to see a list of available tests

If you can't find a suitable solution, you can write to <linux@ispras.ru>.

---=< Bug reporting >=---

If you find a bug, or wish to advise a possible enhancement, please
send an e-mail to ISP RAS <linux@ispras.ru>.

---=< Credits >=---

Copyright (C) 2007-2012 The Linux Foundation.

This program has been developed by ISP RAS <linux@ispras.ru> for LF with some
parts written by Jiri Dluhos <jdluhos@suse.cz>
Copyright (C) 2005-2007 SuSE Linux Products GmbH
