INSTALL - platform/external/ltp - Gitiles

 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 pkgconf 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 travis/*.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.

 GNU Bison / Berkeley Yacc is required for ltp-scanner.

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

 Configuration requires autoconf:

 	$ cd $TOP_SRCDIR
 	$ make autotools
 	$ mkdir -p $TOP_BUILDDIR
 	$ cd $TOP_BUILDDIR && ./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" \
 	  SKIP_IDCHECK=[0|1] \
 	  install

 - Specifying DESTDIR is optional, but required when installing to a non-host
   sysroot, as opposed to the host system's sysroot.
 - Specify SKIP_IDCHECK=1 if and when you don't want to modify /etc/{group,passwd}
   on the target 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" \
 	  SKIP_IDCHECK=[0|1]
 	  install

 - Specifying DESTDIR is optional, but required when installing to a non-host
   sysroot, as opposed to the host system's sysroot.
 - Specify SKIP_IDCHECK=1 if and when you don't want to modify /etc/{group,passwd}
   on the target system's sysroot.

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

 1> tar xzf ltp-XXXXXXXX.tar.gz
 2> cd ltp
 3> ./configure
 4> make all
 5> make install
 6> /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 disk I/O tests can be run by executing the diskio.sh script.  In order
    for these tests to successfully operate a writable high-density 3.5" floppy
    must be in the disk drive and a CD-ROM with more than 100Mb of data must be
    in the CD-ROM drive.  The corresponding tests will fail if either disk is
    missing.

 5. The network tests are executed by running the network.sh script. The network
    tests require some configuration for them to work correctly:

      i) First, there MUST be another test machine setup to act as the server
 	to these client side tests.  This machine MUST have the LTP installed
 	in the same exact location, i.e. if the client has /root/ltp, then the
 	server must have /root/ltp.  This is required because certain tests
 	expect to find server files in certain locations.  Make sure to compile
 	the LTP on this server machine also.

     ii) Second, the server must be setup to allow the client to connect using
 	the "r" commands, such as rsh.  This is done by simply creating/editing
 	the ".rhosts" file under /root.  Place the hostname of the client
 	machine in this file to allow root to remotely connect without the use
 	of a password. If server has the PAM system security tool, you need
 	to add the following lines to /etc/securetty:
 		rlogin
 		rsh
 		rexec
 		pts/0
 		pts/1
 		  :
 		pts/9

    iii) Next, certain services must be activated in order for certain tests to
 	execute.  The following services are activated via inetd/xinetd:
 		rlogind
 		ftpd
 		telnetd
 		echo (stream)
 		fingerd
 		rshd
 	 Also, because certain RPC programs are tested, the portmapper daemon
 	 (rpcbind, or portmap on old distributions) MUST be started, as well as NFS
 	 server AND lock services.

     iv) Finally, before running the network.sh script, two variables must be
 	set: The "RHOST" variable should be set to the hostname of the server.
 	The "PASSWD" variable should be set to root's password on the server
 	machine. This is necessary for tests such as telnet01.sh and ftp01.sh.

    You can now successfully execute the network.sh script.

    You can run the test category which you are interested in, -h option shows
    the list of the test category:
        # ./network.sh -h

    For more info about howto run network.sh 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

 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/build-system-guide.txt.

 Common Issues
 ----------------------

 Issue:    When executing configure it says:

 checking for a BSD-compatible install... /usr/bin/install -c
 checking whether build environment is sane... yes
 checking for gawk... gawk
 checking whether make sets $(MAKE)... yes
 configure: error: cannot run /bin/sh ./config.sub

 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.

 Issue:    When executing make [all] it says:

     " *** No rule to make target `/$*', needed by `pan-all'.  Stop."

 Solution: You must upgrade to make 3.81. Please see the Requirements section above.

 Issue:    When executing make [all] it says something like:

     # ...
     install -m 00644 "/scratch/ltp-dev2/ltp/include/test.h" "/scratch/ltp-install12/include/test.h"
     install -m 00644 "/scratch/ltp-dev2/ltp/include/tlibio.h" "/scratch/ltp-install12/include/tlibio.h"
     install -m 00644 "/scratch/ltp-dev2/ltp/include/usctest.h" "/scratch/ltp-install12/include/usctest.h"
     install -m 00644 "/scratch/ltp-dev2/ltp/include/write_log.h" "/scratch/ltp-install12/include/write_log.h"
     make[1]: Leaving directory `/scratch/ltp-dev2/ltp/include'
     make -C lib -f "/scratch/ltp-dev2/ltp/lib/Makefile" all
     make[1]: Entering directory `/scratch/ltp-dev2/ltp/lib'
     " *** No rule to make target `dataascii.o', needed by `libltp.a'.  Stop." # <-- the error

 Solution: You cannot build LTP with -r / --no-builtin-rules and/or
 	  -R / --no-builtin-variables specified. LTP relies heavily on built-in
 	  implicit rules and variables to function properly.

 Issue:    When executing make (no target, 3.80), it does the following, and doesn't execute all:

     #
     make -C testcases/realtime autotools
     make[1]: Entering directory `/scratch/ltp/testcases/realtime'
     autoheader
     make[1]: Leaving directory `/scratch/ltp/testcases/realtime'
	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 pkgconf 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 travis/*.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.

	GNU Bison / Berkeley Yacc is required for ltp-scanner.

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

	Configuration requires autoconf:

	$ cd $TOP_SRCDIR
	$ make autotools
	$ mkdir -p $TOP_BUILDDIR
	$ cd $TOP_BUILDDIR && ./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" \
	SKIP_IDCHECK=[0\|1] \
	install

	- Specifying DESTDIR is optional, but required when installing to a non-host
	sysroot, as opposed to the host system's sysroot.
	- Specify SKIP_IDCHECK=1 if and when you don't want to modify /etc/{group,passwd}
	on the target 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" \
	SKIP_IDCHECK=[0\|1]
	install

	- Specifying DESTDIR is optional, but required when installing to a non-host
	sysroot, as opposed to the host system's sysroot.
	- Specify SKIP_IDCHECK=1 if and when you don't want to modify /etc/{group,passwd}
	on the target system's sysroot.

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

	1> tar xzf ltp-XXXXXXXX.tar.gz
	2> cd ltp
	3> ./configure
	4> make all
	5> make install
	6> /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 disk I/O tests can be run by executing the diskio.sh script. In order
	for these tests to successfully operate a writable high-density 3.5" floppy
	must be in the disk drive and a CD-ROM with more than 100Mb of data must be
	in the CD-ROM drive. The corresponding tests will fail if either disk is
	missing.

	5. The network tests are executed by running the network.sh script. The network
	tests require some configuration for them to work correctly:

	i) First, there MUST be another test machine setup to act as the server
	to these client side tests. This machine MUST have the LTP installed
	in the same exact location, i.e. if the client has /root/ltp, then the
	server must have /root/ltp. This is required because certain tests
	expect to find server files in certain locations. Make sure to compile
	the LTP on this server machine also.

	ii) Second, the server must be setup to allow the client to connect using
	the "r" commands, such as rsh. This is done by simply creating/editing
	the ".rhosts" file under /root. Place the hostname of the client
	machine in this file to allow root to remotely connect without the use
	of a password. If server has the PAM system security tool, you need
	to add the following lines to /etc/securetty:
	rlogin
	rsh
	rexec
	pts/0
	pts/1
	:
	pts/9

	iii) Next, certain services must be activated in order for certain tests to
	execute. The following services are activated via inetd/xinetd:
	rlogind
	ftpd
	telnetd
	echo (stream)
	fingerd
	rshd
	Also, because certain RPC programs are tested, the portmapper daemon
	(rpcbind, or portmap on old distributions) MUST be started, as well as NFS
	server AND lock services.

	iv) Finally, before running the network.sh script, two variables must be
	set: The "RHOST" variable should be set to the hostname of the server.
	The "PASSWD" variable should be set to root's password on the server
	machine. This is necessary for tests such as telnet01.sh and ftp01.sh.

	You can now successfully execute the network.sh script.

	You can run the test category which you are interested in, -h option shows
	the list of the test category:
	# ./network.sh -h

	For more info about howto run network.sh 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

	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/build-system-guide.txt.

	Common Issues
	----------------------

	Issue: When executing configure it says:

	checking for a BSD-compatible install... /usr/bin/install -c
	checking whether build environment is sane... yes
	checking for gawk... gawk
	checking whether make sets $(MAKE)... yes
	configure: error: cannot run /bin/sh ./config.sub

	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.

	Issue: When executing make [all] it says:

	" *** No rule to make target `/$*', needed by `pan-all'. Stop."

	Solution: You must upgrade to make 3.81. Please see the Requirements section above.

	Issue: When executing make [all] it says something like:

	# ...
	install -m 00644 "/scratch/ltp-dev2/ltp/include/test.h" "/scratch/ltp-install12/include/test.h"
	install -m 00644 "/scratch/ltp-dev2/ltp/include/tlibio.h" "/scratch/ltp-install12/include/tlibio.h"
	install -m 00644 "/scratch/ltp-dev2/ltp/include/usctest.h" "/scratch/ltp-install12/include/usctest.h"
	install -m 00644 "/scratch/ltp-dev2/ltp/include/write_log.h" "/scratch/ltp-install12/include/write_log.h"
	make[1]: Leaving directory `/scratch/ltp-dev2/ltp/include'
	make -C lib -f "/scratch/ltp-dev2/ltp/lib/Makefile" all
	make[1]: Entering directory `/scratch/ltp-dev2/ltp/lib'
	" *** No rule to make target `dataascii.o', needed by `libltp.a'. Stop." # <-- the error

	Solution: You cannot build LTP with -r / --no-builtin-rules and/or
	-R / --no-builtin-variables specified. LTP relies heavily on built-in
	implicit rules and variables to function properly.

	Issue: When executing make (no target, 3.80), it does the following, and doesn't execute all:

	#
	make -C testcases/realtime autotools
	make[1]: Entering directory `/scratch/ltp/testcases/realtime'
	autoheader
	make[1]: Leaving directory `/scratch/ltp/testcases/realtime'