INSTALL

$Id: INSTALL,v 1.36 2010/01/18 23:46:09 yaberauneya Exp $

Requirements
-------------------

1. In order to compile ltp you must have make 3.80+ (make 3.81 preferred).
2. In order to compile and use ltp-scanner (a utility in the pan directory),
   you must have bison/yacc, and flex installed.

bison can be obtained here:
- http://ftp.gnu.org/gnu/bison/bison-2.4.1.tar.gz

Berkeley yacc can be obtained here:
- ftp://invisible-island.net/byacc/byacc.tar.gz

flex can be obtained here:
- http://downloads.sourceforge.net/project/flex/flex/flex-2.5.33/flex-2.5.33.tar.bz2

make 3.81 can be obtained here:
- http://ftp.gnu.org/gnu/make/make-3.81.tar.bz2

If you want to use auto configuration, be sure autoconf-2.61+ & automake-1.10+
are installed.

automake-1.10.2's sources can be downloaded from:
- ftp://ftp.gnu.org/gnu/automake/automake-1.10.2.tar.bz2
- ftp://ftp.gnu.org/gnu/automake/automake-1.10.2.tar.gz

autoconf-2.61's sources can be downloaded from:
- ftp://ftp.gnu.org/gnu/autoconf/autoconf-2.61.tar.bz2
- ftp://ftp.gnu.org/gnu/autoconf/autoconf-2.61.tar.gz

autoconf-2.61 also requires m4-1.4.7+ be installed. Its sources can be
downloaded from:
- http://ftp.gnu.org/gnu/m4/m4-1.4.7.tar.bz2
- http://ftp.gnu.org/gnu/m4/m4-1.4.7.tar.gz

Configuration
-------------------
Using autoconf:
	$ make autotools # This must be run from "$TOP_SRCDIR"!
	$ test -d "$TOP_BUILDDIR" || mkdir -p "$TOP_BUILDDIR"
	$ cd "$TOP_BUILDDIR" && "$TOP_SRCDIR/configure" \
	  # [configure args go here, e.g. CC=$CC, LDFLAGS=$LDFLAGS, etc]

Not using autoconf:

	$ test -d "$TOP_BUILDDIR" || mkdir -p "$TOP_BUILDDIR"
	$ cp "$TOP_SRCDIR/include/config.h.default" \
	     "$TOP_BUILDDIR/include/config.h"
	$ cp "$TOP_SRCDIR/include/mk/config.mk.default" \
	     "$TOP_BUILDDIR/include/mk/config.mk"
	$ cp "$TOP_SRCDIR/include/mk/features.mk.default" \
	     "$TOP_BUILDDIR/include/mk/features.mk"

	# Fire up your favorite editor and set each value appropriately in
	# include/mk/config.mk. Uncomment all values commented out, such as
	# NUMA_LIBS, etc, but only if you're sure that the libraries exist and
	# can be linked on your system.

- $TOP_SRCDIR and $TOP_BUILDDIR are the same for in-build-tree scenarios.
- $TOP_SRCDIR and $TOP_BUILDDIR differ for out-of-build-tree scenarios.

See the In-build-tree and Out-of-build-tree sections below for more details on
what to do next...

Compiling LTP
-------------------

"What's in a Path?"
-------------------

Before getting started, you should make sure that your build directory and
source directory are as basic as possible: no commas, colons, semicolons,
spaces, etc. In fact, this is a relatively good rule of thumb when dealing
with any [Gnu?] make based opensource project.

We won't `fix' the `issues' associated with these particular set of build
errors resulting from non-sane pathnames, because it would introduce unneeded
complexity into the build system and would require non-trivial effort to fix
and validate the third-party packages, and thus wouldn't be a sustainable
model to follow.

So, we apologize for the inconvenience, but using other characters like
underscores and dashes should help when disambiguating words between build
and source pathnames.

In-build-tree
-------------------
In-build-tree support is when you build binaries (applications, binary objects)
in the same directory where the source files reside.

	$ make all
	$ make \
	  "DESTDIR=$SYSROOT" \
	  SKIP_IDCHECK=[0|1] \
	  install

- Specifying DESTDIR is optional, but required when installing to a non-host
  sysroot, as opposed to the host system's sysroot.
- Specify SKIP_IDCHECK=1 if and when you don't want to modify /etc/{group,passwd}
  on the target system's sysroot.

If you get a build error, please report it to ltp-list@lists.sf.net with
following information,

 1. The error output before the failure.
 2. If you used configure:
 	i.   include/config.h
	ii.  include/mk/config.mk
	iii. config.log

Out-of-build-tree
-------------------
Out-of-build-tree support is when you build binaries (applications, binary
objects, generated files) outside of the directory where the source files
reside. This is typically used when cross-compiling for multiple targets.

NOTE: This is by and large correctly implemented, but there are several corner
cases, where this isn't implemented properly. Please see TODO for a list of
items which need fixing in the LTP tree.

	$ mkdir "$OUT_OF_BUILD_TREE_DIR"
	$ make \
	  -C "$OUT_OF_BUILD_TREE_DIR" \
	  -f "$TOP_SRCDIR/Makefile" \
	  "top_srcdir=$TOP_SRCDIR" \
	  "top_builddir=$OUT_OF_BUILD_TREE_DIR"
	$ make \
	  -C "$OUT_OF_BUILD_TREE_DIR" \
	  -f "$TOP_SRCDIR/Makefile" \
	  "top_srcdir=$TOP_SRCDIR" \
	  "top_builddir=$OUT_OF_BUILD_TREE_DIR" \
	  "DESTDIR=$SYSROOT" \
	  SKIP_IDCHECK=[0|1]
	  install

- Specifying DESTDIR is optional, but required when installing to a non-host
  sysroot, as opposed to the host system's sysroot.
- Specify SKIP_IDCHECK=1 if and when you don't want to modify /etc/{group,passwd}
  on the target system's sysroot.

Quick Start
-----------

1> tar xzf ltp-XXXXXXXX.tar.gz
2> cd ltp
3> ./configure
4> make all
5> make install
6> /opt/ltp/runltp

*NOTE:
- LTP assumes the existence of the nobody, bin, and daemon users and their
groups.  If these IDs do not exist, certain tests will fail. The respective
user and group IDs should be the same, i.e. if `nobody's' user ID is 99, then
its group ID should also be 99. The names of the groups are irrelevant.
- The installation directory is /opt/ltp by default. Please see
"Using autoconf" above and specify the appropriate path via --prefix.
DESTDIR= is also honored for install and will install into $DESTDIR/$prefix,
if you want to install into a chroot or a rootfs for instance.

Detailed Installation
---------------------

Beyond the "Quick Start" instructions, there are only a few other things
that should be done.  The Linux Test Project build process uses a
minimalist approach.  There is a lot of room for improvement and
contributions are welcome.

1. Log in as root.

2. Untar the ltp tarball into a spare directory.  There is not a
   standard location for it yet.  We put it in our home directory
   while we're working on it.
   Note that the full path to this location must be accessible for
   unprivileged users, as some tests are run as a different user than root.
   Hence /root is not a good choice on several distributions.

3. Build and install everything, as described above. Note the minimum software
   requirements above before doing so.

4. You can run all of the tests sequentially using the example test script
   runalltests.sh.  The script is provided to get you started.
   See ltp-pan(1) for more information on the test driver we have provided.
   It is simple, but it can do a lot of stuff.

   NOTE: The diskio and network tests will NOT be run by the runltp script;
   they are separate from the other tests because of additional required setup
   overhead.

5. The disk I/O tests can be run by executing the diskio.sh script.  In order
   for these tests to successfully operate a writable high-density 3.5" floppy
   must be in the disk drive and a CD-ROM with more than 100Mb of data must be
   in the CD-ROM drive.  The corresponding tests will fail if either disk is
   missing.

6. The network tests are executed by running the networktests.sh script. The
   network tests require some configuration for them to work correctly:

     i) First, there MUST be another test machine setup to act as the server
	to these client side tests.  This machine MUST have the LTP installed
	in the same exact location, i.e. if the client has /root/ltp, then the
	server must have /root/ltp.  This is required because certain tests
	expect to find server files in certain locations.  Make sure to compile
	the LTP on this server machine also.

    ii) Second, the server must be setup to allow the client to connect using
	the "r" commands, such as rsh.  This is done by simply creating/editing
	the ".rhosts" file under /root.  Place the hostname of the client
	machine in this file to allow root to remotely connect without the use
	of a password. If server has the PAM system security tool, you need
	to add the following lines to /etc/securetty:
		rlogin
		rsh
		rexec
		pts/0
		pts/1
		  :
		pts/9

   iii) Next, certain services must be activated in order for certain tests to
	execute.  The following services are activated via inetd/xinetd:
		rlogind
		ftpd
		telnetd
		echo (stream)
		fingerd
		rshd
	 Also, because certain RPC programs are tested, the "portmapper" daemon
	 MUST be started, as well as NFS server AND lock services.

    iv) Finally, before running the networktests.sh script, two variables must
	be set within the script file.  The "RHOST" variable should be set to
	the hostname of the server.  The "PASSWD" variable should be set to
	root's password on the server machine.  This is necessary for tests
	such as telnet01 and ftp01.

   You can now successfully execute the networktests.sh script.
   When you would like to run the whole network tests, specify -w option:
   	# ./networktests.sh -w

   When you would like to run the same tests which networktests.sh ran till
   2008, specify no option or -d option:
   	# ./networktests.sh

   You can run the test category which you are interested in, -h option shows
   the list of the test category:
   	# ./netwoktests.sh -h


Cross compiling
---------------

To cross compile, you must specify the correct variables:

1. When running configure (CC, CXX, CXXFLAGS, LDLIBS, etc).
2. Manually edit include/mk/config.mk, as described in Configuration.

Note: Do not specify variables on the command-line. Use config.mk instead.

uClinux Users
--------------
Specify UCLINUX=1 when calling make; -DUCLINUX=1 use is deprecated and highly
discouraged.

Variables in Makefile
----------------------

The conventions enforced are standard ones. Here's a quick summary:

CFLAGS   - used when compiling/linking C code, e.g. -D_GNU_SOURCE (no CPPFLAGS!)

CXXFLAGS - used when compiling/linking C++ code (no CPPFLAGS!)

CPPFLAGS - used when preprocessor is run (so C/C++ compiling with $(CPP)
	   functions, e.g. -I$SYSROOT/usr/include -I$SYSROOT/include -I$SYSROOT

LDFLAGS  - linker flags, e.g. "-L$SYSROOT/usr/lib" "-L$SYSROOT/lib". DO NOT
	   PUT LIBRARIES IN THIS LIST (see LDLIBS for that).

LDLIBS   - libraries listed after objects during link, e.g. -lc, -lpthread,
	   -lltp.

See README.mk-devel for a more terse description of what's available.

Common Issues
----------------------

Issue:    When executing configure it says:

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
configure: error: cannot run /bin/sh ./config.sub

Solution: You must upgrade autoconf to 0.10.2+ and m4 to 1.4.7+; config.guess and config.sub aren't necessarily generated with older revisions of the Gnu autotools chain.

Issue:    When executing make [all] it says:

    " *** No rule to make target `/$*', needed by `pan-all'.  Stop."

Solution: You must upgrade to make 3.81. Please see the Requirements section above.

Issue:    When executing make [all] it says something like:

    # ...
    install -m 00644 "/scratch/ltp-dev2/ltp/include/test.h" "/scratch/ltp-install12/include/test.h"
    install -m 00644 "/scratch/ltp-dev2/ltp/include/tlibio.h" "/scratch/ltp-install12/include/tlibio.h"
    install -m 00644 "/scratch/ltp-dev2/ltp/include/usctest.h" "/scratch/ltp-install12/include/usctest.h"
    install -m 00644 "/scratch/ltp-dev2/ltp/include/write_log.h" "/scratch/ltp-install12/include/write_log.h"
    make[1]: Leaving directory `/scratch/ltp-dev2/ltp/include'
    make -C lib -f "/scratch/ltp-dev2/ltp/lib/Makefile" all
    make[1]: Entering directory `/scratch/ltp-dev2/ltp/lib'
    " *** No rule to make target `dataascii.o', needed by `libltp.a'.  Stop." # <-- the error

Solution: You cannot build LTP with -r / --no-builtin-rules and/or
	  -R / --no-builtin-variables specified. LTP relies heavily on built-in
	  implicit rules and variables to function properly.

Issue:    When executing make (no target, 3.80), it does the following, and doesn't execute all:

    #
    make -C testcases/realtime autotools
    make[1]: Entering directory `/scratch/ltp/testcases/realtime'
    autoheader
    make[1]: Leaving directory `/scratch/ltp/testcases/realtime'