view release on metacpan or  search on metacpan

lib/Couchbase/Client/README.pod  view on Meta::CPAN

=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: