1Linux Test Project 2================== 3 4Linux Test Project is a joint project started by SGI, OSDL and Bull developed 5and maintained by IBM, Cisco, Fujitsu, SUSE, Red Hat, Oracle and others. The 6project goal is to deliver tests to the open source community that validate the 7reliability, robustness, and stability of Linux. 8 9The LTP testsuite contains a collection of tools for testing the Linux kernel 10and related features. Our goal is to improve the Linux kernel and system 11libraries by bringing test automation to the testing effort. Interested open 12source contributors are encouraged to join. 13 14Project pages are located at: http://linux-test-project.github.io/ 15 16The latest image is always available at: 17https://github.com/linux-test-project/ltp/releases 18 19The discussion about the project happens at ltp mailing list: 20http://lists.linux.it/listinfo/ltp 21 22The git repository is located at GitHub at: 23https://github.com/linux-test-project/ltp 24 25The patchwork instance is at: 26https://patchwork.ozlabs.org/project/ltp/list/ 27 28Warning! 29======== 30 31**Be careful with these tests!** 32 33Don't run them on production systems. Growfiles, doio, and iogen in particular 34stress the I/O capabilities of systems and while they should not cause problems 35on properly functioning systems, they are intended to find (or cause) problems. 36 37Quick guide to running the tests 38================================ 39 40If you have git, autoconf, automake, m4, the linux headers and the common 41developer packages installed, the chances are the following will work. 42 43``` 44$ git clone https://github.com/linux-test-project/ltp.git 45$ cd ltp 46$ make autotools 47$ ./configure 48``` 49 50Now you can continue either with compiling and running a single test or with 51compiling and installing the whole testsuite. 52 53Shortcut to running a single test 54--------------------------------- 55If you need to execute a single test you actually do not need to compile 56the whole LTP, if you want to run a syscall testcase following should work. 57 58``` 59$ cd testcases/kernel/syscalls/foo 60$ make 61$ PATH=$PATH:$PWD ./foo01 62``` 63 64Shell testcases are a bit more complicated since these need a path to a shell 65library as well as to compiled binary helpers, but generally following should 66work. 67 68``` 69$ cd testcases/lib 70$ make 71$ cd ../commands/foo 72$ PATH=$PATH:$PWD:$PWD/../../lib/ ./foo01.sh 73``` 74 75Open Posix Testsuite has it's own build system which needs Makefiles to be 76generated first, then compilation should work in subdirectories as well. 77 78``` 79$ cd testcases/open_posix_testsuite/ 80$ make generate-makefiles 81$ cd conformance/interfaces/foo 82$ make 83$ ./foo_1-1.run-test 84``` 85 86Compiling and installing all testcases 87-------------------------------------- 88 89``` 90$ make 91$ make install 92``` 93 94This will install LTP to `/opt/ltp`. 95* If you have a problem see `doc/mini-howto-building-ltp-from-git.txt`. 96* If you still have a problem see `INSTALL` and `./configure --help`. 97* Failing that, ask for help on the mailing list or Github. 98 99Some tests will be disabled if the configure script can not find their build 100dependencies. 101 102* If a test returns `TCONF` due to a missing component, check the `./configure` 103 output. 104* If a tests fails due to a missing user or group, see the Quick Start section 105 of `INSTALL`. 106 107To run all the test suites 108 109``` 110$ cd /opt/ltp 111$ ./runltp 112``` 113 114Note that many test cases have to be executed as root. 115 116To run a particular test suite 117 118``` 119$ ./runltp -f syscalls 120``` 121 122To run all tests with `madvise` in the name 123 124``` 125$ ./runltp -f syscalls -s madvise 126``` 127Also see 128 129``` 130$ ./runltp --help 131``` 132 133Test suites (e.g. syscalls) are defined in the runtest directory. Each file 134contains a list of test cases in a simple format, see doc/ltp-run-files.txt. 135 136Each test case has its own executable or script, these can be executed 137directly 138 139``` 140$ testcases/bin/abort01 141``` 142 143Some have arguments 144 145``` 146$ testcases/bin/fork13 -i 37 147``` 148 149The vast majority of test cases accept the -h (help) switch 150 151``` 152$ testcases/bin/ioctl01 -h 153``` 154 155Many require certain environment variables to be set 156 157``` 158$ LTPROOT=/opt/ltp PATH="$PATH:$LTPROOT/testcases/bin" testcases/bin/wc01.sh 159``` 160 161Most commonly, the path variable needs to be set and also `LTPROOT`, but there 162are a number of other variables, `runltp` usually sets these for you. 163 164Note that all shell scripts need the `PATH` to be set. However this is not 165limited to shell scripts, many C based tests need environment variables as 166well. 167 168For more info see `doc/user-guide.txt` or online at 169https://github.com/linux-test-project/ltp/wiki/User-Guidelines. 170 171Developers corner 172================= 173 174Before you start you should read following documents: 175 176* `doc/test-writing-guidelines.txt` 177* `doc/build-system-guide.txt` 178 179There is also a step-by-step tutorial: 180 181* `doc/c-test-tutorial-simple.txt` 182 183If something is not covered there don't hesitate to ask on the LTP mailing 184list. Also note that these documents are available online at: 185 186* https://github.com/linux-test-project/ltp/wiki/Test-Writing-Guidelines 187* https://github.com/linux-test-project/ltp/wiki/Style-Guide 188* https://github.com/linux-test-project/ltp/wiki/Build-System 189* https://github.com/linux-test-project/ltp/wiki/C-Test-Case-Tutorial 190 191Although we accept GitHub pull requests, the preferred way is sending patches to our mailing list. 192 193It's a good idea to test patches on Travis CI before posting to mailing 194list. Our travis setup covers various architectures and distributions in 195order to make sure LTP compiles cleanly on most common configurations. 196For testing you need to sign up to Travis CI, enable running builds on your LTP fork on 197https://travis-ci.org/account/repositories and push your branch. 198