=head1 NAME

Couchbase::Client::README - README for Couchbase::Client

=head1 Introduction

Couch::Couchbase is a Perl client for Couchbase (http://www.couchbase.org).

The couchbase client is a smart, vbucket-aware client. What this means is that
Couchbase::Client can tap into your Couchbase cluster, with the client needing
to be able to access (initially) only a single entry point.

The module provides:

=head2 Synchronous Interface: Couchbase::Client

This is the simplest and most tested interface. The methods are self-explanatory.
Additionally, the return type is complex and detailed, allowing error reporting
for any unexpected conditions (something severely lacking in any Memcache client
implementation).

=head2 Legacy Interface: Couchbase::Client::Compat

Drop-in replacement for Cache::Memcached and Cache::Memcached::Fast.

I can't say it's 100% compatible yet, but the basic methods have been implemented.
Internally it just wraps around the new interface

=head2 Asynchronous Framework for Perl: Couchbase::Client::Async

Provides the necessary functions and utilities needed to make a POE, IO::Async,
etc. client for Couchbase.

=head2 Mock Server Interface: Couchbase::MockServer

Interface to the Java C<CouchbaseMock.jar>. This is a work in progress.

=head2 Extra Components

=head3 Couchbase::Config - REST API module

This module will probably be a dependency for full testing, but will not necessarily
be part of this distribution. It's currently available as a separate repository
on github.

=head3 Couchbase::VBucket - VBucket server mapping module

Just a little utility module. May be useful for testing.


=head1 Installing

The following components are required for a proper C<Couchbase::Client>

=over

=item libcouchbase >= 1.0.1 (L<release|http://www.couchbase.com/develop/c/current>)

=item libvbucket >= 1.8.0.2 (L<release|http://www.couchbase.com/develop/c/current>)

=item libevent >= 1.4

=item libsasl/libsasl2 (any version).

=item Java (for the tests).

=back

All of the above components (except Java) are bundled in source form with the
tarball distribution (see further).

=head2 Building Couchbase::Client

Couchbase::Client is bundled (in its tarball distribution) with source distributions
of libevent, libisasl, libvbucket, and libcouchbase. These are not present on
the git version because it is assumed that the user may want to provide copies
of their own.

The bundled configuration will only substitute I<missing> dependencies from
the bundle; thus, if you have C<libsasl> but are missing a proper version of
C<libevent>, then only the bundled libevent (but not libsasl) will be used.

C<Couchbase::Client> can be configured to either link against the bundled
libraries, or to link against a custom or system directory.

=head3 Using Embedded Libraries:

In order to use embedded libraries, you should ensure that you have a proper
distribution for each needed and unfound library.

The file C<PLCB_Config.pm> should contain a bunch of hash entries in the format
of 

    LIBFOO_RELEASE => 1.2.3-sdff
    
where C<LIBFOO> is the uper-case name of the library, and the value is the
version of the library.

The tarball B<must> be named C<libfoo-1.2.3-sdff.tar.gz>, and its top-level
directory must be C<libfoo-1.2.3/>

You will find that the config file has sane defaults, and that the main task
is downloading them.

The tarballs should then be relocated to the C<src/> directory.

Once all is ready, you can invoke the C<Makefile.PL> script, optionally
passing some arguments.

=head4 Makefile.PL arguments

=over

=item --libpath

A string for passing to the linker which should contain something like
C<-L/foo -L/bar> etc.

This is only necessary if your standard dependencies are found outside the linker's
default search path (e.g. macports)

=item --incpath

This is the same as C<--libpath>, but are passed to the preprocessor and would
look like C<-I/usr/foo/include> etc.

=back

Thus you can invoke somehting like:

    $ perl Makefile.PL --incpath=-I/opt/local/include --libpath=-L/opt/local/lib
    $ make
    $ make test # but see the testing section, later
    $ make install
    
=head3 Providing your own libraries.

This is a relatively straight-forward option, and is what I use for development.

Simply make use of the aforementioned C<--libpath> and C<--incpath> arguments to
point to the directory which contains the necessary dependencies, and follow
the relevant parts from the above section.


There are some top-level scripts. Some have meaning to only the author, some might
be useful.

If you would like to generate the perl MANIFEST, run the C<gen_manifest.pl>
script.

Also, check out the runnable modules in the C<t/> directory

=head2 Testing

The tests in this module require java to run. Some tests furthermore will only
work on a real cluster, due to some of the limitations in the Java client.

A C<CouchbaseMock.jar> should be located within the C<t/tmp> directory. You can
obtain one from L<here|http://files.couchbase.com/maven2/org/couchbase/mock/CouchbaseMock/0.5-SNAPSHOT/CouchbaseMock-0.5-20120202.071818-12.jar>

To run the tests on a real cluster, you can make use of the
C<PLCB_TEST_REAL_SERVER> environment variable.

When set, it should/can contain something like this:

    PLCB_TEST_REAL_SERVER='bucket=my_bucket,username=secret,memd_port=11212'
    
The keys available are

=over

=item username, password

Authentication information

=item bucket

Which bucket to use (default is C<default>)

=item server

Which server to connect to (default is C<localhost:8091>)

=item memd_port

Required for some tests. This is the authless port for memcached client access.

=back

=head3 KNOWN ISSUES

=over

=item *

32 Bit perls will have arithmetic results stringified if their value is greater
than 32 bits.


=item *

Some tests within the test suite will fail in some unices (but not linux, from
what i've seen) with the following message:

        t/01-main.t .. 1/? 
    #   Failed test 'have single error'
    #   at /home/mordy/Couchbase-Client-0.16_0/blib/lib/Couchbase/Test/Settings.pm line 262.
    #   (in Couchbase::Test::Settings->T25_multi_server_list)
    #          got: '2'
    #     expected: '1'
    t/01-main.t .. 162/? # Looks like you failed 1 test of 166.
    t/01-main.t .. Failed 1/166 subtests 
        (less 1 skipped subtest: 164 okay)


This is not a fatal error, and is being worked on

=item *

Asynchronous tests (and the reference POE implementation) will not work properly
on NetBSD due to a weird L<kernel bug|http://gnats.netbsd.org/cgi-bin/query-pr-single.pl?number=46077>


=item *

I have not even bothered to figure out how to compile this on Windows. Mingw32
will be supported eventually, but probably not MSVC.

=back