
  IMS Open Corpus Workbench: CWB/Perl CL API Version 3.5.0

  compatible with CWB version 3.5.0


This package contains a Perl interface to the low-level corpus access library
(CL) of the IMS Open Corpus Workbench.  Note that you will need a working C
compiler (the same used to compile your version of Perl) in order to build and
install this package. 


PREREQUISITES

Before compiling the CWB/Perl package, you must install an up-to-date version
of the IMS Open Corpus Workbench (see above for precise version requirements),
known for short as the "CWB Core".

You can either compile the CWB Core from source or install a binary package;
see instructions and links at https://cwb.sourceforge.io/.

If you did not install the CWB Core in a standard place (i.e. a directory in 
your search path), make sure that the "cwb-config" program can be executed
from the command line.  This will enable the CWB/Perl makefile to obtain the
necessary configuration information.

You will also need a working C compiler (the same used to compile your version
of Perl).  If you have installed a binary distribution of the CWB Core, the CL 
library (libcl.<a,so,dylib>) included there might not be compatible with your 
C compiler.  In that case, you will need to compile the CWB Core from source.


QUICK INSTALLATION GUIDE

If you have never installed a Perl module before: don't despair.  All you
have to do -- provided that the prerequisites are met -- is to execute the
following commands:

    perl Makefile.PL
    make
    make test
    make install

You will probably have to login as root for the last step (or you can type
"sudo make install" and enter your normal password).  If you want to install
the Perl modules in a non-standard location, say in "~/perl/lib/perl5/..."
and "~/perl/man/...", type the following instead of "perl Makefile.PL":

    perl Makefile.PL PREFIX=~/perl INSTALLMAN1DIR=~/perl/man/man1

Note that you will then have to include the appropriate subdirectories of
"~/perl/lib/perl5/" in your Perl search path in order to use the CWB modules.

If the "cwb-config" utility is not in your standard search path, you can 
specify its location with the --config option, for example:

    perl Makefile.PL --config=/opt/cwb-3.5/bin/cwb-config


TROUBLESHOOTING

 - On many Unix platforms (including Mac OS X), /usr/local/lib is always
   included in the library search path. If you have installed some version of
   CWB under the default prefix /usr/local, the library file
   /usr/local/lib/libcl.a will be picked up and cannot be overridden by the
   settings from cwb-config. There is no known work-around for the problem at
   the moment. If you need to work with multiple versions of CWB, make sure
   none of them is installed in /usr/local.


PACKAGE OVERVIEW

This package installs two Perl modules:

    CWB::CL           Perl API for the low-level CWB corpus access library
    CWB::CL::Strict   convenience wrapper for automatic error checking

Unfortunately, there is no complete documentation yet for the CWB::CL module
(neither for the CWB Corpus Library itself).  Type "perldoc CWB::CL" for a
synopsis of the CL API and its usage from Perl.  Note that most of the methods
defined by CWB::CL correspond directly to functions in the CL library.

A good starting point for your own work with CWB::CL is the commented example
script in the "examples/" subdirectory.  If you have installed the CWB demo
corpus (DICKENS), you should be able to run "perl examples/dickens.perl" (set
the CORPUS_REGISTRY environment variable if necessary).

The script "examples/benchmark.perl" allows you to test the performance of the
CWB::CL interface and compare it to the older CL.pm module (provided that the
old module is still installed on your system).


COPYRIGHT

Copyright (C) 1999-2022 by Stephanie Evert [https://purl.org/stephanie.evert]

This software is provided AS IS and the author makes no warranty as to
its use and performance. You may use the software, redistribute and
modify it under the same terms as Perl itself.
