[libmarpa-r2-perl] 01/06: Add doc re shared library testing

[Jonas Smedegaard]

This is an automated email from the git hooks/post-receive script.

js pushed a commit to annotated tag Marpa-R2-2.085_005
in repository libmarpa-r2-perl.

commit 85d24cc0f75d4e8155e17a9214c334d1d211277a
Author: Jeffrey Kegler <JKEGL at cpan.org>
Date:   Sun Apr 27 11:09:20 2014 -0700

    Add doc re shared library testing
---
 cpan/etc/README_shared_test.txt | 72 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)

diff --git a/cpan/etc/README_shared_test.txt b/cpan/etc/README_shared_test.txt
new file mode 100644
index 0000000..8e9b963
--- /dev/null
+++ b/cpan/etc/README_shared_test.txt
@@ -0,0 +1,72 @@
+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*\""

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-perl/packages/libmarpa-r2-perl.git