John Beppu > Embedix-DB > Embedix::DB

Download:
Embedix-DB-0.05.tar.gz

Dependencies

Annotate this POD

Related Modules

Pod::Usage
Embedix::ECD
more...
By perlmonks.org
View/Report Bugs
Module Version: 0.05   Source  

NAME ^

Embedix::DB - persistence for ECDs

SYNOPSIS ^

instantiation

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

    # $edb should be an instance of Embedix::DB::Pg

adding a distro

    $edb->addDistro (
        name  => 'uCLinux 2.4',
        board => 'm68k',
    );

    $edb->addDistro (
        name  => 'Embedix 1.2',
        board => 'ppc',
    );

selecting a distro to work on

    $edb->workOnDistro(name => 'Embedix 1.2', board => 'ppc');

cloning a distro

    $edb->cloneDistro(board => 'mpc8260adsp');

updating a distro with new information

    my $apache_ecd = Embedix::ECD->newFromFile('apache.ecd');
    $edb->updateDistro(ecd => $apache_ecd);

deleting components from a distro

    $edb->deleteNode(name => 'busybox');

REQUIRES ^

Embedix::ECD

This is needed to get data from ECD files into perl objects that can then be inserted into a database.

DBD::Pg

The PostgreSQL backend uses this.

DBD::mysql

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

DESCRIPTION ^

The "DB" in Embedix::DB stands for database. Although Embedix::DB was inspired by the 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 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.

CONCEPTS ^

distro

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

board

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

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.

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.

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.

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.

Initialization

First, one must connect to a database.

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},
        ],
    );

$edb will be an instance of Embedix::DB::Pg in this example.

workOnDistro(distro => $str, board => $str)

This method is used to set the current working distribution. This method is usually called immediately after the new(), because almost all other methods require that a current working distribution has been set. (The only exception is addDistro()).

    $edb->workOnDistro(distro => 'Embedix 1.2', board => 'i386');

Methods for defining distributions

Now that a connection to the database has been made, the database may be populated.

addDistro

This adds a new distribution to the database.

updateDistro

This takes data from an ECD and populates the current working database with it.

cloneDistro

This takes the current working distribution and makes an exact clone of it. This method exists to make it easy to create variations on a distribution using a sort of inheritance. For example, the "Embedix 1.2" distro may have the following variations.

    generic
    |-- i386
    |-- mips
    |-- ppc
    |   `-- mpc8260adsp
    `-- sh
        |-- sh3
        `-- sh4

generic would be a distro containing data from only architecturally neutral ECDs. The i386, mips, ppc, and sh versions of "Embedix 1.2" would be derived from generic by using cloneDistro(). They would then be populated with additional data from architecturally-specific ECDs. ECD nodes may be removed as well as with the case for the mpc8260adsp. Since it doesn't have a graphics controller, it doesn't make sense to provide the X11 packages, so the mpc8260adsp would be a cloned ppc distribution w/ the X11 packages removed.

unrelateNode

This is used to dissociate a node from a distro.

relateNode

This is used to associate a node with a distro.

deleteNode

This totally deletes a node. If a node has been cloned many times, all the clones go away. This is more serious than unrelateNode().

Methods for querying the database

This is an area that still needs to be fleshed out. As Embedix::Config matures, this API will mature as well to.

getComponentList

This returns an arrayref of the form:

    [
        [ '/category0' [ $node0, $node1, ... ] ],
        [ '/category1' [ $node0, $node1, ... ] ],
        ...
    ];

The list of categories as well as the list of nodes within each category come sorted in ASCII order.

getDistroList

This returns an arrayref of the form:

    [
        [ 'distro0' [ $board0, $board1, ... ] ],
        [ 'distro1' [ $board0, $board1, ... ] ],
        ...
    ];

This is a list of distributions where each distribution has a list of which boards it supports. The board lists are sorted in ASCII order.

DIAGNOSTICS ^

error messages

COPYRIGHT ^

Copyright (c) 2000,2001 John BEPPU. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR ^

John BEPPU <beppu@lineo.com>

SEE ALSO ^

related perl modules

Embedix::ECD(3pm), Embedix::Config(3pm)

syntax highlighting: