INSTALL

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