Last updated: 15 Sep 2010
How to update the Libevent embedded in OPAL
-------------------------------------------
OPAL requires some modification of the Libevent build system in order
to properly operate. In addition, OPAL accesses the Libevent functions
through a set of wrappers - this is done for three reasons:
1. Hide the Libevent functions. Some applications directly call
libevent APIs and expect to operate against a locally installed
library. Since the library used by OPAL may differ in version, and
to avoid linker errors for multiply-defined symbols, it is
important that the libevent functions included in OPAL be "hidden"
from external view. Thus, OPAL's internal copy of libevent is built
with visibility set to "hidden" and all access from the OPAL code
base is done through "opal_xxx" wrapper API calls.
In those cases where the system is built against a compiler that
doesn't support visibility, conflicts can (unfortunately)
arise. However, since only a very few applications would be
affected, and since most compilers support visibility, we do not
worry about this possibility.
2. Correct some deficiencies in the distributed Libevent configuration
tests. Specifically, the distributed tests for kqueue and epoll
support provide erroneous results on some platforms (as determined
by our empirical testing). OPAL therefore provides enhanced tests
to correctly assess those environments.
3. Enable greater flexibility in configuring Libevent for the specific
environment. In particular, OPAL has no need of Libevent's dns,
http, and rpc events, so configuration options to remove that code
from Libevent have been added.
The procedure for updating Libevent has been greatly simplified
compared to prior versions in the OPAL code base by replacing
file-by-file edits with configuration logic. Thus, updating the
included libevent code can generally be accomplished by:
1. create a new opal/mca/event component for the updated version, using
a name "libeventxxx", where xxx = libevent version. For example,
libevent 2.0.7 => component libevent207
2. create a subdirectory "libevent" in the new component and unpack the
new libevent code tarball into it.
3. copy the configure.m4, autogen.subdirs, component.c, moduule.c,
Makefile.am, and .h files from a prior version to the new component.
You will need to customize them for the new version, but they can
serve as a good template. In many cases, you will just have to update
the component name.
4. edit libevent/configure.in to add OMPI specific options and modes.
Use the corresponding file from a prior version as a guide. The
necessary changes are marked with "OMPI" comments. These changes
have been pushed upstream to libevent, and so edits may no longer
be required in the new version.
5. Modify libevent/Makefile.am. Here again, you should use the file from
a prior version as an example. Hopefully, you can just use the file
without change - otherwise, the changes will have to be done by hand.
Required changes reflect the need for OMPI to turn "off" unused
subsystems such as http. These changes have been pushed upstream to
libevent, and so edits may no longer be required in the new version.
6. in your new component Makefile.am, note that the libevent headers
are listed by name when WITH_INSTALL_HEADERS is given. This is required
to support the OMPI --with-devel-headers configure option. Please review
the list and update it to include all libevent headers for the new
version.
