Brief instruction on building the JNI-DLL/shared library from "BSF4Rexx.cc"
---------------------------------------------------------------------------

For a new operating system platform you need to compile "BSF4Rexx.cc", which is a C (C++)
program using the "Java Native Interface (JNI)" and allowing Java to call the exported
C/C++ function via JNI as well.

"BSF4Rexx.cc" using the supplied Makefiles can be built with MS C++, and with gcc on the
other platforms (the rather old OS/2 version used to be compilable with IBM's VCPP or
Watson's C++).


Maybe a few background infos ad creating a shared library from "BSF4Rexx.cc":

    * Download homepage: <http://wi.wu-wien.ac.at/rgf/rexx/bsf4rexx/current/>

          o <http://wi.wu-wien.ac.at/rgf/rexx/bsf4rexx/current/BSF4Rexx_install.zip>

                + binary distribution, unzip it (a directory "bsf4rexx" will be
                  created) and have CLASSPATH point to the files "bsf-v240-20061006.jar",
                  "commons-logging-1.1.jar", and "bsf-rexx-engine.jar"

                + all of the above jar's also containt the respective Java source

          o <http://wi.wu-wien.ac.at/rgf/rexx/bsf4rexx/current/BSF4Rexx_sources.zip>

                + source-distribution, unzip it (directories "source_cc" and
                 "source_java" will be created)

                + you need to work with the "source_cc" and try to compile and
                  use the program "BSF4Rexx.cc"

                      # the Linux Makefile using gcc can be found in "lin_bsf4rexx.mak",
                        at the top its usage is listed:

                            * make -f lin_bsf4rexx [orexx | regina | clean | clean_dll | rebuild ]

    * Compiling "BSF4Rexx.cc"

          o You need to have the JDK installed and point to its  include directories
           (just look into/adapt the make file)

    * Testing/running the compiled DLL/shared library

          o Setting up the BSF4Rexx-library

                + force a link into "${JDK_BASE}/jre/lib/i386" (no idea how that may be named
                  on your OS), which is for Java's trusted use of a JNI library

                      # this one is needed, if Java needs to load the ooRexx interpreter
                        via the BSF4Rexx library; ie. the Rexx program in question is
                        launched via Java (using the shell script "rexxj.sh")

                + force a link into the lib directory on OSX or set LD_LIBRARY_PATH to point
                  to the BSF4Rexx lib

                      # this one is needed for ooRexx to load BSF4Rexx and interface with
                        Java, ie. the Rexx program in questin is launched via ooRexx (using
                        the binary "rexx")

                + add the directory which contains "BSF.CLS" (ooRexx program that
                  loads the BSF4Rexx library, if necessary, and which camouflages
                  Java as ooRexx), "infoBSF.rex" (classic Rexx program, not needing
                  BSF.CLS), "infoBSF-oo.rex" (ooRexx program, needing BSF.CLS), and
                  "BSF4Rexx_info2html.rex" (a classic Rexx program not needing
                  BSF.CLS, writing HTML to stdout which depicts the Java configuration
                  in use)  to the PATH environment

          o Testing: the following is a suggested sequence of tests, where the
            latter test should only be run, if the former worked

                + Try to run the classic-Rexx program "rexx infoBSF.rex" which
                  directly uses the BSF4Rexx library to load and interact with Java

                + Try to run the classic-Rexx program "./rexxj.sh infoBSF.rex"
                  which tries to use Java to dispatch the Rexx program

                + Try to run the classic-Rexx program "rexx infoBSF-oo.rex"
                  (needs to use  "BSF.CLS") which directly uses the BSF4Rexx
                  library to load and interact with Java

                + Try to run the classic-Rexx program "./rexxj.sh infoBSF-oo.rex"
                  (needs to use  "BSF.CLS") which tries to use Java to dispatch
                  the Rexx program

                + Finally, you can document your Java-related configuration in
                use by running "rexx BSF4Rexx_info2html.rex > javaConfig4BSF4Rexx.html"

    * Further things (now that you are able to have fun! ;) ):

          o locate the "samples" directory within the installation directory
            "bsf4rexx" (result of unzipping "BSF4Rexx_install.zip")

          o run the samples, there are also Lee Peedin's impressive samples
            from the 2006 International Rexx symposium there!

    * Now, if that is all working, I would have the request to adapt the BSF4Rexx
      installation script to match your environment (if that is necessary):

          o setupJava.rex

                + this script is meant for Linux systems where Java is not installed
                  such that it could be invoked from the commandline, but instead
                  points to the stubs; running this scripts allows to find out which
                  Java installations are on the machine and allows one to choose which
                  Java installation to use by default

                + this is only meant as a "last-resort", if the user is otherwise
                  not able to install Java on Linux

          o setupBSF.rex

                + this script analyzes the Java configuration and creates

                      # "bsf4rexx.sh" (allows to run BSF4Rexx-Rexx-scripts
                        without the need to any permanent environment changes

                      # "installBSF4Rexx.sh" (creates a shell/batch installation
                        script to copy the files to the appropriate directories)

                      # "setEnvironment4BSF4Rexx.sh" (creates a shell/batch script
                        to configure your environment; could/should be copied to
                        your login shell script)

                      # "uninstallBSF4Rexx.sh" (creates a shell/batch uninstallation
                        script to delete the BSF4Rexx files from the directories, which
                        "installBSF4Rexx.sh" copied them to)

          o setupOOo.rex

                + this script analyzes the OpenOffice (OOo)location and creates
                  an install, uninstall, and setEnvironment script

                      # "installOOo.sh" (creates a shell/batch installation script
                        and copies the ooRexx macros support file to the respective
                        OOo directory, then installs that OOo package directly into
                        OOo; after doing that, all instances of OOo - including the
                        quickstarter, if present - must be closed; this will force
                        OOo upon the next start to scan all its installed packages)

                      # "setEnvironment4OOo.sh" (creates a shell/batch script to
                        configure your environment; could/should be copied to your
                        login shell script)

                      # "uninstallOOo.sh" (creates a shell/batch uninstallation script
                        to delete the OOo file from the OOo directory, uninstalling
                        the macro ooRexx package)


If you succeeded to build a new working JNI please submit the Makefile, any
changes that may have been necessary in the source code, and the built binary!

Good luck and all the best !

---rony
<mailto:Rony.Flatscher@wu-wien.ac.at>

