README

X.Org GTest testing environment for Google Test
===============================================

Provides a Google Test environment for starting and stopping
a X server for testing purposes. The actual environment is defined in header
environment.h. Please refer to the Google test documentation for information
on how to add a custom environment.

Moreover, a custom main() function that takes care of setting up the
environment is provided in xorg-gtest_main.cpp. This can be used as a
replacement for libgtest_main.a

Using X.org GTest in a project
==============================

The X.org GTest does not provide precompiled libraries. Each project must build
the X.org GTest sources. To facilitate this, aclocal and automake include files
are provided. Perform the following to integrate xorg-gtest into an autotools-
based project.

Add the following line to the top level Makefile.am for your project:

ACLOCAL_AMFLAGS = -I m4 --install

This will ensure the latest xorg-gtest.m4 macro installed on your system is
copied into aclocal/. If a user runs autoreconf, they will already have the
macro even if they don't have xorg-gtest installed.

Call CHECK_XORG_GTEST from configure.ac This will set the value of
$have_xorg_gtest and set $(XORG_GTEST_CPPFLAGS) and $(XORG_GTEST_CXXFLAGS).

The last step is to modify your test automake rules for compiling and using
xorg-gtest. There are two methods to do this: simplified or manual.

Simplified
----------

This method requires less changes to your Makefile.am, but has a few drawbacks:

* xorg-gtest is compiled only once. If you need multiple versions of xorg-gtest
  or gtest compiled with different flags, you will need to use the manual
  method.
* The flags used to compile xorg-gtest must be the same as the flags used to
  compile the tests. This means any flags other than XORG_GTEST_CPPFLAGS and
  XORG_GTEST_CXXFLAGS must be provided through the AM_CPPFLAGS and AM_CXXFLAGS
  variables.

Copy Makefile-xorg-gtest.am into your project.

In your test Makefile.am, add:

include $(top_srcdir)/path/to/Makefile-xorg-gtest.am

Append $(XORG_GTEST_BUILD_LIBS) to check_LIBRARIES.

Append CPPFLAGS with $(XORG_GTEST_CPPFLAGS) and CXXFLAGS with
$(XORG_GTEST_CXXFLAGS) for any testing source objects.

Finally, link against $(XORG_GTEST_LIBS). If you want the xorg-gtest main()
integration, link against $(XORG_GTEST_MAIN_LIBS) as well.

Manual
------

This method is more flexible, but it requires the user to modify the Makefile.am
file manually. It is recommended that the user be familiar with automake before
attempting.

Copy the contents of Makefile-xorg-gtest.am into your Makefile.am file. Adjust
the compilation flags as needed, keeping in mind that all non-warning flags must
match the flags used when compiling the test cases. Remove the gtest and/or
xorg-gtest main() library targets if you will not use them. Copy the gtest and
xorg-gtest library targets if multiple builds with different compilation flags
are needed. Finally, link the tests with the appropriate gtest and xorg-gtest
libraries and their dependencies: libpthread and libX11.

Environment variables
---------------------
XORG_GTEST_XSERVER_SIGSTOP
  If set, an XServer object will raise a SIGSTOP signal after startup.
XORG_GTEST_XSERVER_KEEPALIVE
  If set, the XServer object will ignore calls to Terminate() or Kill().
  This is useful for debugging a server without having the test terminate
  the process while still looking at gdb output.
XORG_GTEST_CHILD_STDOUT
  If set to any value, Process::Start() will _not_ close stdout/stdin/stderr
  for the forked child.
XORG_GTEST_USE_VALGRIND
  Set to the valgrind command to use when starting a process. Options must
  be space-separated, e.g. "valgrind --leak-check=full --someotherarg"
  Not limited to valgrind, you can specify any executable here.