INSTALL

   1 $Id: INSTALL,v 1.27 2009/10/25 10:44:14 yaberauneya Exp $
   2
   3 Requirements
   4 -------------------
   5 In order to compile and use pan, you must have bison/yacc and flex installed.
   6
   7 bison can be obtained here:
   8 - http://ftp.gnu.org/gnu/bison/bison-2.4.1.tar.gz
   9
  10 Berkeley yacc can be obtained here:
  11 - ftp://invisible-island.net/byacc/byacc.tar.gz
  12
  13 flex can be obtained here:
  14 - http://downloads.sourceforge.net/project/flex/flex/flex-2.5.33/flex-2.5.33.tar.bz2
  15
  16 If you want to use auto configuration, be sure autoconf-2.61+ & automake-1.10+
  17 are installed.
  18
  19 automake-1.10.2's sources can be downloaded from:
  20 - ftp://ftp.gnu.org/gnu/automake/automake-1.10.2.tar.bz2
  21 - ftp://ftp.gnu.org/gnu/automake/automake-1.10.2.tar.gz
  22
  23 autoconf-2.61's sources can be downloaded from:
  24 - ftp://ftp.gnu.org/gnu/autoconf/autoconf-2.61.tar.bz2
  25 - ftp://ftp.gnu.org/gnu/autoconf/autoconf-2.61.tar.gz
  26
  27 autoconf-2.61 also requires m4-1.4.7+ be installed. Its sources can be
  28 downloaded from:
  29 - http://ftp.gnu.org/gnu/m4/m4-1.4.7.tar.bz2
  30 - http://ftp.gnu.org/gnu/m4/m4-1.4.7.tar.gz
  31
  32 Configuring
  33 -------------------
  34 Using autoconf:
  35         $ make autotools # This must be run from "$TOP_SRCDIR!"
  36         $ test -d "$TOP_BUILDDIR" || mkdir -p "$TOP_BUILDDIR"
  37         $ cd "$TOP_BUILDDIR" && "$TOP_SRCDIR/configure" \
  38           # [configure args go here, e.g. CC=$CC, LDFLAGS=$LDFLAGS, etc]
  39
  40 Not using autoconf:
  41
  42         $ test -d "$TOP_BUILDDIR" || mkdir -p "$TOP_BUILDDIR"
  43         $ cp "$TOP_SRCDIR/include/config.h.default" \
  44              "$TOP_BUILDDIR/include/config.h"
  45         $ cp "$TOP_SRCDIR/include/mk/config.mk.default" \
  46              "$TOP_BUILDDIR/include/mk/config.mk"
  47
  48         # Fire up your favorite editor and set each value appropriately in
  49         # include/mk/config.mk. Uncomment all values commented out, such as
  50         # NUMA_LIBS, etc, but only if you're sure that the libraries exist and
  51         # can be linked on your system.
  52
  53 - $TOP_SRCDIR and $TOP_BUILDDIR are the same for in-build-tree scenarios.
  54 - $TOP_SRCDIR and $TOP_BUILDDIR differ for out-of-build-tree scenarios.
  55
  56 See the In-build-tree and Out-of-build-tree sections below for more details on
  57 what to do next...
  58
  59 Compiling LTP
  60 -------------------
  61
  62 In-build-tree
  63 -------------------
  64 In-build-tree support is when you build binaries (applications, binary objects)
  65 in the same directory where the source files reside.
  66
  67         $ make all
  68         $ make \
  69           "DESTDIR=$SYSROOT" \
  70           SKIP_IDCHECK=[0|1] \
  71           install
  72
  73 - Specifying DESTDIR is optional, but required when installing to a non-host
  74   sysroot, as opposed to the host system's sysroot.
  75 - Specify SKIP_IDCHECK=1 if and when you don't want to modify /etc/{group,passwd}
  76   on the target system's sysroot.
  77
  78 If you get a build error, please report it to ltp-list@lists.sf.net with
  79 following information,
  80
  81  1. The error output before the failure.
  82  2. If you used configure:
  83         i.   include/config.h
  84         ii.  include/mk/config.mk
  85         iii. config.log
  86
  87 Out-of-build-tree
  88 -------------------
  89 Out-of-build-tree support is when you build binaries (applications, binary
  90 objects, generated files) outside of the directory where the source files
  91 reside. This is typically used when cross-compiling for multiple targets.
  92
  93 NOTE: This is by and large correctly implemented, but there are several corner
  94 case, where this isn't implemented properly. Please see TODO for a list of items
  95 which need fixing in the LTP tree.
  96
  97         $ mkdir "$OUT_OF_BUILD_TREE_DIR"
  98         $ make \
  99           -C "$OUT_OF_BUILD_TREE_DIR" \
 100           -f "$TOP_SRCDIR/Makefile" \
 101           "top_srcdir=$TOP_SRCDIR" \
 102           "top_builddir=$OUT_OF_BUILD_TREE_DIR"
 103         $ make \
 104           -C "$OUT_OF_BUILD_TREE_DIR" \
 105           -f "$TOP_SRCDIR/Makefile" \
 106           "top_srcdir=$TOP_SRCDIR" \
 107           "top_builddir=$OUT_OF_BUILD_TREE_DIR" \
 108           "DESTDIR=$SYSROOT" \
 109           SKIP_IDCHECK=[0|1]
 110           install
 111
 112 - Specifying DESTDIR is optional, but required when installing to a non-host
 113   sysroot, as opposed to the host system's sysroot.
 114 - Specify SKIP_IDCHECK=1 if and when you don't want to modify /etc/{group,passwd}
 115   on the target system's sysroot.
 116
 117 Quick Start
 118 -----------
 119
 120 1> tar xzf ltp-XXXXXXXX.tar.gz
 121 2> cd ltp
 122 3> make
 123 4> make install
 124 5> ./runalltests.sh
 125
 126 *NOTE: The LTP assumes the existence of the nobody, bin, and daemon users and
 127 their groups.  If these IDs do not exist, certain tests will fail. The users
 128 and groups IDs should be the same, i.e. if user "nobody" is 99, then it's
 129 group should also be "99". The names of the groups are irrelevant.
 130
 131
 132 Detailed Installation
 133 ---------------------
 134
 135 Beyond the "Quick Start" instructions, there are only a few other things
 136 that should be done.  The Linux Test Project build process uses a
 137 minimalist approach.  There is a lot of room for improvement and
 138 contributions are welcome.
 139
 140 1. Log in as root.
 141
 142 2. Untar the ltp tarball into a spare directory.  There is not a
 143    standard location for it yet.  We put it in our home directory
 144    while we're working on it.
 145    Note that the full path to this location must be accessible for
 146    unprivileged users, as some tests are run as a different user than root.
 147    Hence /root is not a good choice on several distributions.
 148
 149 3. Build and install everything, as described above. Note the minimum software
 150    requirements above before doing so.
 151
 152 4. You can run all of the tests sequentially using the example test script
 153    runalltests.sh.  The script is provided to get you started.
 154    See ltp-pan(1) for more information on the test driver we have provided.
 155    It is simple, but it can do a lot of stuff.
 156
 157    NOTE: The diskio and network tests will NOT be run by the runalltests.sh
 158    script. They are separate from the other tests because of the additional
 159    required setup overhead.
 160
 161 5. The disk I/O tests can be run by executing the diskio.sh script.  In order
 162    for these tests to successfully operate a writable high-density 3.5" floppy
 163    must be in the disk drive and a CD-ROM with more than 100Mb of data must be
 164    in the CD-ROM drive.  The corresponding tests will fail if either disk is
 165    missing.
 166
 167 6. The network tests are executed by running the networktests.sh script. The
 168    network tests require some configuration for them to work correctly:
 169
 170      i) First, there MUST be another test machine setup to act as the server
 171         to these client side tests.  This machine MUST have the LTP installed
 172         in the same exact location, i.e. if the client has /root/ltp, then the
 173         server must have /root/ltp.  This is required because certain tests
 174         expect to find server files in certain locations.  Make sure to compile
 175         the LTP on this server machine also.
 176
 177     ii) Second, the server must be setup to allow the client to connect using
 178         the "r" commands, such as rsh.  This is done by simply creating/editing
 179         the ".rhosts" file under /root.  Place the hostname of the client
 180         machine in this file to allow root to remotely connect without the use
 181         of a password. If server has the PAM system security tool, you need
 182         to add the following lines to /etc/securetty:
 183                 rlogin
 184                 rsh
 185                 rexec
 186                 pts/0
 187                 pts/1
 188                   :
 189                 pts/9
 190
 191    iii) Next, certain services must be activated in order for certain tests to
 192         execute.  The following services are activated via inetd/xinetd:
 193                 rlogind
 194                 ftpd
 195                 telnetd
 196                 echo (stream)
 197                 fingerd
 198                 rshd
 199          Also, because certain RPC programs are tested, the "portmapper" daemon
 200          MUST be started, as well as NFS server AND lock services.
 201
 202     iv) Finally, before running the networktests.sh script, two variables must
 203         be set within the script file.  The "RHOST" variable should be set to
 204         the hostname of the server.  The "PASSWD" variable should be set to
 205         root's password on the server machine.  This is necessary for tests
 206         such as telnet01 and ftp01.
 207
 208    You can now successfully execute the networktests.sh script.
 209    When you would like to run the whole network tests, specify -w option:
 210         # ./networktests.sh -w
 211
 212    When you would like to run the same tests which networktests.sh ran till
 213    2008, specify no option or -d option:
 214         # ./networktests.sh
 215
 216    You can run the test category which you are interested in, -h option shows
 217    the list of the test category:
 218         # ./netwoktests.sh -h
 219
 220
 221 Cross compiling
 222 ---------------
 223
 224 To cross compile, you must specify the correct variables:
 225
 226 1. When running configure (CC, CXX, CXXFLAGS, LDLIBS, etc).
 227 2. Manually edit include/mk/config.mk, as described in Configuration.
 228
 229 Note: Do not specify variables on the command-line. Use config.mk instead.
 230
 231 uClinux Users
 232 --------------
 233 Specify UCLINUX=1 when calling make; -DUCLINUX=1 use is deprecated and highly
 234 discouraged.
 235
 236 Variables in Makefile
 237 ----------------------
 238
 239 The conventions enforced are standard ones. Here's a quick summary:
 240
 241 CFLAGS   - used when compiling/linking C code, e.g. -D_GNU_SOURCE (no CPPFLAGS!)
 242
 243 CXXFLAGS - used when compiling/linking C++ code (no CPPFLAGS!)
 244
 245 CPPFLAGS - used when preprocessor is run (so C/C++ compiling with $(CPP)
 246            functions, e.g. -I$SYSROOT/usr/include -I$SYSROOT/include -I$SYSROOT
 247
 248 LDFLAGS  - linker flags, e.g. "-L$SYSROOT/usr/lib" "-L$SYSROOT/lib". DO NOT
 249            PUT LIBRARIES IN THIS LIST (see LDLIBS for that).
 250
 251 LDLIBS   - libraries listed after objects during link, e.g. -lc, -lpthread,
 252            -lltp.
 253
 254 See README.mk-devel for a more terse description of what's available.