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