KinoSearch::Docs::DevGuide 0.15

KinoSearch::Docs::DevGuide is a Perl module for hacking/debugging KinoSearch.

SYNOPSIS

Developer-only documentation. If you just want to build a search engine, you probably dont need to read this.

Fundamental Classes

Most of the classes in KinoSearch rely on KinoSearch::Util::Class and KinoSearch::Util::ToolSet, so youll probably want to familiarize yourself with them.

Object Oriented Design

No public member variables.

Multiple classes defined within a single source-code file, e.g. TermQuery and TermWeight, may use direct access to get at each others member variables. Everybody else has to use accessor methods.

C-struct based classes such as TermInfo allow direct access to their members, but only from C (of course).

Subroutine/method access levels

There are three access levels in KinoSearch.

public: documented in "visible" pod.

private: subs which are prepended with an _underscore may only be used within the package in which they reside -- as per perlstyle guidelines -- and in only one source file.

distro: any sub which doesnt fall into either category above may be used anywhere within the KinoSearch distribution.

Documentation Conventions

KinoSearchs public API is defined by what you get when you run the suite through a well-behaved pod-to-whatever converter. Developer-only documentation is limited to comments and "invisible" =for/=begin POD blocks.

Integration of XS and C code

XS and C code in KinoSearch is stored faux-Inline-style, after an __END__ token, and delimited by either __XS__, __H__, or __C__. A heavily customized Build.PL detects these code blocks and writes out hard files at install-time, so the inlining is mostly for convenience while editing: the XS code is often tightly coupled to the Perl code in a given module, and having everything in one place makes it easier to see whats going on and move things back and forth.

Build.PL writes out separate .h and .c files for each block it finds, but all the XS blocks are concatenated into a single file -- KinoSearch.xs. The content of KinoSearch.xs consists of the XS block from KinoSearch.pm, followed by all the other XS blocks in an undetermined order. Ultimately, only a single compiled library gets installed along with the Perl modules.

At runtime, the only module which calls XSLoader::load is KinoSearch. Because the KinoSearch MODULE has many PACKAGEs, use KinoSearch; loads all of the XS routines in the entire KinoSearch suite. A pure-Perl version of KinoSearch.pm which did the same thing might look like this...

package KinoSearch;
our $VERSION = 1.0;

package KinoSearch::Index::TermInfo;

sub get_doc_freq {
# ...
}

package KinoSearch::Store::InStream;

sub lu_read {
# ...
}

# ...

Since KinoSearch.xs is only generated/modified when Build.PL is run, an extra command line call to Build.PL has to be integrated into the development workflow when working on XS or C material.

% perl Build.PL; ./Build code; perl -Mblib t/some_test.t

Build.PL tracks modification times, using them to determine whether it needs to recompile anything. If only pure Perl modules have been edited, it wont force needless recompilation, and if only a limited number of .pm files containing XS/C/H code have been edited, it will recompile as little as it can.