third_party_ltp/INSTALL

Requirements
------------

Tools are needed for LTP compilation. They should be available as a
package in any Linux distribution (no specific version is required).

Debian / Ubuntu

	# apt install gcc git make pkgconf autoconf automake bison flex m4 linux-headers-$(uname -r) libc6-dev

openSUSE / SLES

	# zypper install gcc git make pkg-config autoconf automake bison flex m4 linux-glibc-devel glibc-devel

Fedora / CentOS / RHEL

	# yum install gcc git make pkgconf autoconf automake bison flex m4 kernel-headers glibc-headers

These are minimal build requirements for git compilation. Some tests require
extra development files of some libraries, see ci/*.sh. There is also
support for other Linux distributions not listed here.

autoconf, automake, m4 (autoconf requirement), git and pkgconf (or pkg-config
on older distros) are required only for compilation from git (used for creating
configure file).

pkgconf is recommended also for compilation from tarball as it
does automatic detection of some library support.

Configuration
-------------

Configuration requires autoconf:

	$ cd $TOP_SRCDIR
	$ make autotools
	$ mkdir -p $TOP_BUILDDIR
	$ cd $TOP_BUILDDIR && $TOP_SRCDIR/configure # configure args go here, e.g. CC=$CC, LDFLAGS=$LDFLAGS, etc

- $TOP_SRCDIR and $TOP_BUILDDIR are the same for in-build-tree scenarios.
- $TOP_SRCDIR and $TOP_BUILDDIR differ for out-of-build-tree scenarios.

See the In-build-tree and Out-of-build-tree sections below for more details on
what to do next.

Compiling LTP
-------------

In-build-tree
-------------

In-build-tree support is when you build binaries (applications, binary objects)
in the same directory where the source files reside.

	$ make all
	$ make \
	  "DESTDIR=$SYSROOT" \
	  install

- Specifying DESTDIR is optional, but required when installing to a non-host
  sysroot, as opposed to the host system's sysroot.

If you get a build error, please report it to ltp@lists.linux.it with
following information,

 1. The error output before the failure.
 2. If you used configure:
	i.   include/config.h
	ii.  include/mk/config.mk
	iii. config.log

Out-of-build-tree
-----------------

Out-of-build-tree support is when you build binaries (applications, binary
objects, generated files) outside of the directory where the source files
reside. This is typically used when cross-compiling for multiple targets.

NOTE: This is by and large correctly implemented, but there are several corner
cases, where this isn't implemented properly. Please see TODO for a list of
items which need fixing in the LTP tree.

	$ mkdir "$OUT_OF_BUILD_TREE_DIR"
	$ make \
	  -C "$OUT_OF_BUILD_TREE_DIR" \
	  -f "$TOP_SRCDIR/Makefile" \
	  "top_srcdir=$TOP_SRCDIR" \
	  "top_builddir=$OUT_OF_BUILD_TREE_DIR"
	$ make \
	  -C "$OUT_OF_BUILD_TREE_DIR" \
	  -f "$TOP_SRCDIR/Makefile" \
	  "top_srcdir=$TOP_SRCDIR" \
	  "top_builddir=$OUT_OF_BUILD_TREE_DIR" \
	  "DESTDIR=$SYSROOT" \
	  install

- Specifying DESTDIR is optional, but required when installing to a non-host
  sysroot, as opposed to the host system's sysroot.

Quick Start
-----------

	$ tar xzf ltp-XXXXXXXX.tar.gz
	$ cd ltp
	$ ./configure
	$ make all
	# make install
	$ /opt/ltp/runltp

*NOTE:
- LTP assumes the existence of the nobody, bin, and daemon users and their
groups.  If these IDs do not exist, certain tests will fail. The respective
user and group IDs should be the same, i.e. if `nobody's' user ID is 99, then
its group ID should also be 99. The names of the groups are irrelevant.
- The installation directory is /opt/ltp by default. Please see
"Using autoconf" above and specify the appropriate path via --prefix.
DESTDIR= is also honored for install and will install into $DESTDIR/$prefix,
if you want to install into a chroot or a rootfs for instance.

Detailed Installation
---------------------

Beyond the "Quick Start" instructions, there are only a few other things
that should be done.  The Linux Test Project build process uses a
minimalist approach.  There is a lot of room for improvement and
contributions are welcome.

1. Log in as root.

2. Untar the ltp tarball into a spare directory.  There is not a
   standard location for it yet.  We put it in our home directory
   while we're working on it.
   Note that the full path to this location must be accessible for
   unprivileged users, as some tests are run as a different user than root.
   Hence /root is not a good choice on several distributions.

3. Build and install everything, as described above. Note the minimum software
   requirements above before doing so.

4. The network tests related installation see testcases/network/README.md.

Cross compiling
---------------

To cross compile, you must specify the correct variables when running configure.
e.g. CC, LDFLAGS, etc.
For correct pkgconf / pkg-config detection you need to set
PKG_CONFIG_SYSROOT_DIR=$SYSROOT

After configure has run, it will generate include/mk/config.mk. You can tweak
settings in there if need be, but you should not specificy settings on the
command-line when running make.

32 bit build on 64 bit machine
------------------------------

You need to set CFLAGS=-m32 LDFLAGS=-m32 and PKG_CONFIG_LIBDIR

* RPM based distributions (openSUSE, Fedora, etc.)
PKG_CONFIG_LIBDIR=/usr/lib/pkgconfig CFLAGS=-m32 LDFLAGS=-m32 ./configure

* Debian / Ubuntu and derivates
PKG_CONFIG_LIBDIR=/usr/lib/i386-linux-gnu/pkgconfig CFLAGS=-m32 LDFLAGS=-m32 ./configure

* Arch Linux
PKG_CONFIG_LIBDIR=/usr/lib32/pkgconfig CFLAGS=-m32 LDFLAGS=-m32 ./configure

Kernel modules
--------------

LTP contains few kernel modules and tests which are using them.
These require to be built with the same kernel headers as the running kernel (SUT).
Sometimes the best way to achieve this is to compile them on the SUT.

Due Linux Kernel Driver Interface unstability [1], error during building kernel
modules does not break the build. Make errors fatal can be done by FORCE_MODULES=1
make variable.

'modules', 'modules-clean' and 'modules-install' make targets are shortcuts
to build just these modules and tests.

[1] https://docs.kernel.org/process/stable-api-nonsense.html

Android Users
-------------

Specify ANDROID=1 when calling make. Many tests which would otherwise work are
currently not built because they share a directory with an incompatible test.

The shell scripts expect /bin/sh to exist, so create a symlink.

Variables in Makefile
---------------------

The conventions enforced are standard ones. Here's a quick summary:

CFLAGS   - used when compiling/linking C code, e.g. -D_GNU_SOURCE (no CPPFLAGS!)

CPPFLAGS - used when preprocessor is run (so C/C++ compiling with $(CPP)
	   functions, e.g. -I$SYSROOT/usr/include -I$SYSROOT/include -I$SYSROOT

LDFLAGS  - linker flags, e.g. "-L$SYSROOT/usr/lib" "-L$SYSROOT/lib". DO NOT
	   PUT LIBRARIES IN THIS LIST (see LDLIBS for that).

LDLIBS   - libraries listed after objects during link, e.g. -lc, -lpthread,
	   -lltp.

For other variables and more info about the build systems see
doc/developers/build_system.rst.