view release on metacpan or  search on metacpan

DB.pm  view on Meta::CPAN

The PostgreSQL backend uses this.

=item DBD::mysql

If anyone writes a MySQL backend, it'll surely use this.

=back

=head1 DESCRIPTION

The "DB" in Embedix::DB stands for database.  Although Embedix::DB was
inspired by the B<tigger> code that implements the original Embedix
Database, the implementation strategy is quite different.

First, Embedix::DB is a means to provide persistence for data found in
ECD files.  Tigger uses the filesystem for this purpose.  Embedix::DB
may have a filesystem-based backend in the future, but the current
implementation provides a PostgreSQL-based backend.  The goal here was
to minimize the amount of parsing necessary to start an Embedix
configuration program (like TargetWizard).  By doing the CPU-intensive
parsing stage only once for when an Embedix distribution is initially
defined, startup can be much faster.  TargetWizard currently parses a
large collection of ECDs every time it starts up.

Beyond that, it has the ability to take ECD data and organize it
at a higher level into distributions.  Currently, it is awkward to use
a single TargetWizard installation to provide the ability to configure
different distributions.  For example, you could not use TargetWizard to
configure both a uCLinux distribution and an Embedix distribution during
the same session.  In order to do this, one would currently have to exit
TargetWizard, install a new config that points to the appropriate
directories, and restart TargetWizard.  Although tigger is theoretically
capable of handling this more gracefully, the directory structure for
how ECDs are stored doesn't facilitate this.  In contrast, Embedix::DB
was designed from the beginning to be able to manipulate multiple
distributions simultaneously.

Another area where Embedix::DB deviates from tigger is in node names
for ECDs.  Tigger requires that all nodes must have B<unique> names
regardless of the node's nesting.  Embedix::DB does not have this
restriction.  Hopefully, this will allow node names to be less contrived
in the future.

One significant difference between Embedix::DB and tigger is that
Embedix::DB does not handle dependency and conflict resolution.  That
job is delegated to Embedix::Config which will use an instance of
Embedix::DB to get information from the database when necessary.  Also
note that Embedix::DB does not know how to parse or generate ECD files.
That job belongs to Embedix::ECD.  Tigger does many things, and its
parts are tightly coupled making it difficult to use any given part of
it in isolation from the rest of tigger.  The functionality provided by
tigger is roughly equivalent to the functionality provided by
Embedix::ECD, Embedix::DB, and Embedix::Config.  (I need to make this
paragraph flow better).

The overall theme of Embedix::DB is to try to improve upon the areas
where tigger is lacking.  It's a lot of work, and I'd like to emphasize
that I'm not doing this out of disrespect.  Surely, I would have made
many of the same mistakes (and some original ones of my own) if I were
implementing this without the benefit of hindsight.  I believe the
concept of TargetWizard is a good one, and that's why I'm doing this.

Embedix::DB is an exploratory work where I am trying to put certain
ideas about how tigger could be improved into practice.

=head1 CONCEPTS

=over 8

=item distro

Short for "distribution".  Examples:  'Embedix 1.2', 'uCLinux 2.4'.
Distros are collections of ECDs.

=item board

A board is a name for a piece of hardware that a distro has been
ported to.  Examples:  'i386', 'm68k', 'ppc', 'alpha'.

=item node

From ECDs, the data enclosed within a <GROUP>, <COMPONENT>, <OPTION>,
<AUTOVAR>, or <ACTION> tag is the data of a node.  Nodes may be nested.

=item database

This is where it's all stored.  The underlying implementation may be
something other than a 'real' database.  For example, the filesystem
with a specific directory structure may be providing persistence.  We
still call that a database -- just play along.

=item cloning

When creating a derivative of a distro, it is convenient (and space
efficient) to use the cloneDistro() method to create a clone to work
on.  Think of it as a form of inheritance.

=back

=head1 METHODS

The Embedix::DB API provides methods for performing abstract operations
on the database.  Whether the backend is based on a filesystem or a
relational database, the same API should be applicable.

=head2 Initialization

First, one must connect to a database.

=over 4

=item new(backend => $str, source => $source_ref)

This instantiates an Embedix::DB with the appropriate backend.

    my $edb = Embedix::DB->new(
        backend => 'Pg',
        source  => [
            'dbi:Pg:dbname=embedix', $user, $pass,
            { AutoCommit => 0},