INSTALL

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