# Copyright 2014 Jeffrey Kegler
# This file is part of Marpa::R2.  Marpa::R2 is free software: you can
# redistribute it and/or modify it under the terms of the GNU Lesser
# General Public License as published by the Free Software Foundation,
# either version 3 of the License, or (at your option) any later version.
#
# Marpa::R2 is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser
# General Public License along with Marpa::R2.  If not, see
# http://www.gnu.org/licenses/.

I've added the ability to test external shared libraries to Marpa::R2.

Note the primary intent is to test *external* shared libraries in
arbitrary places, so by default the test fails because it cannot find a
shared library.  This behavior may be a little perplexing if you stumble
into it by accident, because in the course of setting up shared library
testing, you do need to create one.

Doesn't let "principle of least surprise" dictate that Marpa::R2
by default find the shared library it created?  Here I invoke the
"principle of least dangerous surprise".  Forcing the user to specify
explicitly which shared library minimizes the risk that he is testing
against the wrong library, and usually the test results from the shared
library inside Marpa::R2 will *not* be those of interest.

Here are the details.  (I am assuming a Linux environment.)

1.)  In the Marpa::R2 cpan directory:

  rm -r blib_shared  libmarpa_shared

This step is optional, and assures you a clean environment.

2.)  In the Marpa::R2 cpan directory:

     ./Build code --libmarpa-shared=1

3.)  To test you need to tell the system where to find the shared library
that you are interested in.  It does *not* assume that it is the one you've
just built.  This is done differently on different systems, but in Linux
this works:

    LD_LIBRARY_PATH=$HOME/stage/libmarpa_dist/.libs ./Build test --libmarpa-shared=1

LD_LIBRARY_PATH tells Linux where to look for additional shared libraries.
If LD_LIBRARY_PATH were not specified the test would fail.

4.)  If you really want to test the library that was built in step 2, you
have to find it and point the library search path to it.  Currently it is
in libmarpa_shared/.libs in the cpan directory and so this works on Linux:

    LD_LIBRARY_PATH=libmarpa_shared/.libs  ./Build test --libmarpa-shared=1

Note 1:  You can't install the shared library that Marpa::R2 creates.
This is a feature.  To create a shared library for installation, you
should copy the libmarpa distribution outside the Marpa::R2 directory
structure, make the needed changes, (for example, you may need to convert
libmarpa's version number to some new scheme), and then copy it to the
destination you've picked.

Note 2: In the "--libmarpa-shared=1" flag, the assignment to 1 is necessary.
Otherwise Module::Build assumes that you've set "libmarpa-shared" to undefined.

Note 3: To be sure you are actually testing the library you hope you
are testing, libmarpa now has a "tag", which can be set at compile
time and which can identify every compilation uniquely.  By default,
if you compile with GCC, the tag is a time stamp, recording when the
preprocessor was run.  You can also set the tag explicitly:

    ./configure MARPA_DEBUG_FLAG=-DMARPA_TAG=testing123

The tag appears early in the test output:

    t/00-load.t ............ 1/4 # Marpa::R2 version is 2.085_004
    # Libmarpa version is 6.0.3
    # Libmarpa tag: testing123

You can put spaces and other non-word characters into the tag, but you have to
figure out how to make them run the guantlet from shell to Makefile to compiler
command line.  Here's an example who works on Linux:

    ./configure MARPA_DEBUG_FLAG="\"-DMARPA_TAG=*This is a test*\""