jepp - Java Embedded Python

   Copyright (c) 2004, 2005, 2006 Mike Johnson.

   This file is licenced under the the zlib/libpng License.

   This software is provided 'as-is', without any express or implied

   warranty. In no event will the authors be held liable for any

   damages arising from the use of this software.

   Permission is granted to anyone to use this software for any

   purpose, including commercial applications, and to alter it and

   redistribute it freely, subject to the following restrictions:

       1. The origin of this software must not be misrepresented; you

       must not claim that you wrote the original software. If you use

       this software in a product, an acknowledgment in the product

       documentation would be appreciated but is not required.

       2. Altered source versions must be plainly marked as such, and

       must not be misrepresented as being the original software.

       3. This notice may not be removed or altered from any source

       distribution.

Comments welcome.

	- Mike Johnson <mrjohnson0@users.sourceforge.net>

    DEPENDENCIES

        - Python version >= 2.2

        - JNI >= 1.2 (untested, preferably 1.4)

    BUILDING ON LINUX/UNIX

        Simply ./configure && make && make install.

    BUILDING ON MAC OS X

        You'll need to:

            - set JAVA_HOME to /Library/Java/Home *not* /usr.

            - compile Python or download it using Fink.

            - have installed the developer kits from Apple

            - make a symlink from libjep.dynlib to /Library/Java/Extentions, like:

                sudo ln -s `pwd`/.libs/libjep.dylib \

                    /Library/Java/Extensions/libjep.jnilib

                *** Make sure to use '.jnilib' for the symlink. ***

              (This will get added to the install script Very Soon Now.)

    AUTOMAKE 1.6

        If you're using automake > 1.4, please run the `autogen.sh`

script before running configure. This includes Mac OS X.

    WINDOWS

        You'll need MSVC 6 and Python 2.3. I've compiled successfully

against the ActiveState version. The project file expects Java in

C:\j2sdk1.4.2_04 and Python in C:\Python2.3. If these aren't correct

paths, you should edit the project settings.

        Otherwise, the build is pretty normal. Notice there's no debug

version. Feel free to add one if you like.

        Also, you'll likely need to add -Djava.library.path='path to

Release folder' for testing. Or copy and register the DLL in the

System directory.

    RUNNING ON *NIX - Preparing the libraries

        Due to some (common) difficulties with Java and C projects

that dlopen libraries, you'll need to set LD_PRELOAD environment

variable. That's in addition to setting LD_LIBRARY_PATH if you've

installed libjep into a directory not cached by ld.so.

        For example, my tomcat startup.sh script starts with this:

            #!/bin/sh

            # java memory setting

            export JAVA_OPTS='-Xmx64m'

            # force system to load python

            export LD_PRELOAD=/usr/lib/libpython2.3.so.1.0

            # this is where my libjep.so is.

            export LD_LIBRARY_PATH=/share/jepp/jep/.libs

        Adding some heap memory is a good idea, too.

        The libpython used here is whatever you've compiled jep

against. If you don't know, try this command:

            $ ldd .libs/libjep.so.1.0.0

                < ... blah ... >

            	libpython2.3.so.1.0 => /usr/lib/libpython2.3.so.1.0 (0x40023000)

        That's the libpython you want to set in

LD_PRELOAD. Unfortunately, this means you'll have to change this if

you upgrade python. If it's the wrong library, it will most likely

cause a crash. If it's not set you'll get an exception similar to:

"Python Encountered: exceptions.ImportError:

/usr/lib/python2.3/lib-dynload/datetime.so: undefined symbol:

PyObject_GenericGetAttr".

    RUNNING - Down to business

        First, fire off the test.py script. We want to make sure

you're fully setup. To start with, export LD_LIBRARY_PATH and

LD_PRELOAD as in the section above. Then, start with:

            java -classpath ../ jep.Test 0

        A lot of early bugs in Jep didn't appear until the code is

stressed a little. The above 0 argument is the number of additional

threads to create. They all run through the test.py script in sub

intepreters. Go ahead, throw some threads at it.

            $ time java -classpath ../ jep.Test 3

                real	0m0.344s

                user	0m0.260s

                sys	0m0.050s

            $ time java -classpath ../ jep.Test 50

                real	0m1.944s

                user	0m1.850s

                sys	0m0.100s

        The test script isn't designed for speed but it runs quickly

enough.