pyclene is designed to be built with Python's standard build system, distutils.  End-user-oriented documentation for distutils is available at http://www.python.org/doc/current/inst/inst.html , but you probably won't need to read it unless you encounter a problem with the instructions in this file.

distutils is not reliant on make, so CLucene's make-based build is expected to be irrelevant to most pyclene users.

CLucene requires a reasonably standards-compliant C++ compiler, such as GCC 3+ or Microsoft Visual C++ 7+.  Obviously, pyclene inherits this requirement, with the additional constraint that the compiler used to build pyclene must be compatible with the one used to build Python itself.

pyclene supports Python 2.3 and later.


===============
Windows
===============

The standard Windows distribution of Python 2.3 is built with MSVC 6, while Python 2.4 is built with MSVC 7.1 (7.1 is the version in Visual Studio 2003).  Those who wish to use pyclene on Windows have several options, discussed below.

  -------
  Options
  -------
  1. Use prebuilt Windows binaries of pyclene.  As of this writing (2004.11.25), no such binaries have been made available, but they will be as soon as pyclene is fully integrated into the CLucene project.

  2. Compile pyclene with Python 2.3 or later and the MinGW port of GCC.

  3. Compile pyclene with Python 2.4 and Visual Studio 2003.

  4. Compile pyclene with Python 2.4 and the free "Microsoft Visual C++ Toolkit 2003".

  -------
  Details
  -------
  1. [YYY:  To be written later, when binaries are available.]

  2. Compile pyclene with Python 2.3 or later and the MinGW port of GCC.
     Download and install MinGW (http://mingw.org ).  Include at least the following packages:
       - binutils
       - gcc-core
       - gcc-g++
       - mingw-runtime
       - mingw-utils
       - w32api
     The 'bin' subdirectory of the MinGW installation directory must be on your PATH, but MinGW's POSIX-style shell environment, MSYS, is not required.

     Make sure the directory where python.exe resides is on your PATH.  Invoke the batch file 'compile-mingw.bat' in the 'wrappers/python' directory of the CLucene source tree.  Warnings and error messages (if any) generated by GCC during the compilation process are stored in the 'nodist_err.txt' file.

     Python's distutils system will build pyclene and place the resulting binaries in a subdirectory of the 'build' directory.  On the example system, running Windows 2000 and Python 2.3, the name of the subdirectory was 'lib.win32-2.3'.  Within that directory is a directory named 'pyclene', which should contain the files '_cl_c.pyd', '_cl_py.py', '__init__.py', and 'lucene.py'.

     Next, read the "After compilation" section below.

  3. Use Python 2.4 and Visual Studio 2003.
     If the Visual Studio 2003 directories were not registered in the appropriate environment variables during the installation process, run the 'vcvars32.bat' file in the same command prompt window you plan to use to compile pyclene.

     Make sure the directory where python.exe resides is on your PATH.  Invoke the batch file 'compile-msvc.bat' in the 'wrappers/python' directory of the CLucene source tree.  Warnings and error messages (if any) generated by MSVC during the compilation process are stored in the 'nodist_err.txt' file.

     Python's distutils system will build pyclene and place the resulting files in a subdirectory of the 'build' directory.  On the example system, running Windows 2000 and Python 2.4c1, the name of the subdirectory was 'lib.win32-2.4'.  Within that directory is a directory named 'pyclene', which should contain the files '_cl_c.pyd', '_cl_py.py', '__init__.py', and 'lucene.py'.

     Next, read the "After compilation" section below.

  4. Use Python 2.4 and the free "Microsoft Visual C++ Toolkit 2003".
     Configuring the free toolkit to compile and link pyclene is possible, but far too complicated for the scope of this document.  Unless you're prepared to invest a large amount of time, use MinGW (Option #2 above) instead.  If you're determined to use the free MSVC toolkit, read the documents listed below.  Remember that configuring the free toolkit to compile pyclene is complicated by the fact that CLucene and pyclene are written in C++, rather than C.
    1. http://www.vrplumber.com/programming/mstoolkit/
   [If you still have questions after #1, such as those related to the C++ STL:]
    2. http://aspn.activestate.com/ASPN/Mail/Message/Python-win32/2206851
    3. http://aspn.activestate.com/ASPN/Mail/Message/Python-win32/2207376

     After the toolkit is installed and configured, follow the instructions for Option #3 above.


===========================================
Posix-compliant Unix-like operating systems
===========================================

If your system doesn't already have GCC 3 or later and Python 2.3 or later, install them.  Most Linux distributions released in 2004 or later include the prerequisites.  To determine which versions of GCC and Python you have, issue the commands 'gcc -v' and 'python -V', respectively.

To build pyclene, switch to the 'wrappers/python' directory in the CLucene source tree and issue the command:
  python setup.py build

Alternatively, invoke the script 'compile.sh', which stores any warnings/errors from the C++ compiler in the 'nodist_err.txt' file.

If the build process is successful, distutils will place a compiled copy of pyclene in a system-dependent subdirectory of the 'build' directory.  On the example system, the x86 Linux distribution Fedora Core 3 with Python 2.3.4, this directory is entitled 'lib.linux-i686-2.3'.  Within that directory is a directory named 'pyclene', which should contain the files '_cl_c.so', '_cl_py.py', '__init__.py', and 'lucene.py'.

Next, read the "After compilation" section below.


=================
After compilation
=================

If you want to verify that pyclene works as expected on your system before proceeding to installation, follow the instructions in the file 'test.txt'.  NOTE THAT YOU CAN RUN THE TEST SUITE WITHOUT HAVING "INSTALLED" PYCLENE; if pyclene was built in the standard way, the test suite will automatically figure out where the binaries reside.

To install pyclene, issue the following command in the 'wrappers/python' directory: 
  python setup.py install

Since the directory structure of a Python installation is typically not writable by ordinary users, you'll probably need to execute the command from an administrative account.  If you're unable to do that, you can instead place the 'build/lib.[OS-name]-[arch-name]-[Python-version]' directory on your PYTHONPATH.

The 'setup.py install' command will bytecode-compile the Python modules of pyclene, then copy both the Python modules and the C++ binaries to a directory where Python can find them.  On the example system, Python 2.3.4 was installed in /opt/rush/python/core/py23, so distutils placed pyclene in /opt/rush/python/core/py23/lib/python2.3/site-packages/pyclene.