view release on metacpan or  search on metacpan

lib/Myco/Devel.pod  view on Meta::CPAN

=head1 NAME

Myco::Devel - myco Developer's Guide.

=head1 DESCRIPTION

This guide is intended for developers wanting to build applications with myco.
You should have a decent grasp of the Perl programming language, or else a
solid grasp of another programming language (C, PHP, etc.). Familiarity with
Object Oriented Programming (OOP) techniques and test-first methodology of
developing programs (such as outlined in the "eXtreme Programming" method)
also go a long way toward writing sound applications, and making the best use
of features offered in myco.

Our goal in this manual is to write and run a small application based on the
myco framework.

Most likely, you will also be functioning as your own sysadmin. If so, please
consult the L<Myco System Administration Guide|Myco::Admin> for how-tos on 
installing Perl, PostresSQL, module dependencies, myco-deploying the database,
etc. This document will repeat some of the details from the Admin guide along
the way.

Also note that the assumption running through this guide that you're working on
some variant of Unix or Linux. This is just to Keep It Simple Stupid. Nothing
would thrill us more than to see widespread Windows myco-deployments of myco. Please
hit the mailing list or the myco blog (L<http://www.mycohq.com/>) if you are
attempting such a thing and run into trouble.

=head1 Myco::App::Guitar - first myco entity class!

The simplest way to get started, after completing L<installation|Myco::Admin>
and L<initial configuration|Myco::Admin/"Deploying the Database"> of myco, is
to utilize L<myco-mkentity> to create a new Myco entity class and its companion
test class. Depending on how you like to structure your module files and what
testing framework you like to use (L<myco-mkentity> and L<myco-testrun> currently use
L<Test::Class|Test::Class> with L<Test::Unit|Test::Unit>), this may not suit you. But for this guide,
it'll have to do :)

First, be sure that you've set a couple environment variables. Assuming you've
downloaded and untarred/unzipped the myco distribution into your home
directory and renamed it just 'myco', in C<sh> or C<bash>:

  export MYCO_ROOT=/usr/home/yourhomedir/myco

In C<csh> or C<tcsh>:

  setenv MYCO_ROOT /usr/home/yourhomedir/myco

Put it in your .bashrc or .cshrc for permanence, if you like. Now navigate
there:

  cd $MYCO_ROOT

Now, after contemplating the object you'd like to model in your class and the
name you want to give to it, run C<myco-mkentity>:

  ./bin/myco-mkentity Myco::App::Guitar

Though you can name your class anything, a good place to start is to park it
within the Myco perl namespace, making use of the 'App' area. This has been
historically used as a collection point or sandbox for developing myco
applications. Anyway, using C<myco-mkentity> requires you to do it this way.

You can now poke around your new class file:

   vi lib/Myco/App/Guitar.pm

and your companion test class file:

   vi test/Myco/App/Guitar/Test.pm

Once you're satisfied its all there, give the test a whirl!

  % ./bin/myco-testrun Myco::App::Guitar::Test
  ......
  Time:  0 wallclock secs ( 0.01 usr +  0.01 sys =  0.02 CPU)

By default, your new test class will not test for persistence bahavior:

  skip_persistence => 1 # in the %test_parameters hash of your test class

This is desirable, since its entirely possible that you want to simply use the
myco framework to write classes to work in-memory only, and not persist as
objects in a database. In this case, you'd proceed to write your code, but all
attributes would be of a transient nature. But in most cases - such as now -
you'll want to utilize persistence. So turn persistence testing on:

  skip_persistence => 0

and run the test again. It should crash and burn, ending like this:

  !!!FAILURES!!!
  Test Results:
  Run: 6, Failures: 0, Errors: 3

So, we now want to configure your class in the myco framework to be
persistent, so that these six initial persistence tests will pass.

The Guitar.pm module file generated my L<myco-mkentity> provides two dummy
attributes (fooattrib and barattrib) to get persistence started. This should
suffice to prove that persistence will work. One thing you might want to do
before remyco-deploying the database is to specify your own DB table name. In the
L<Myco::Entity::Meta|Myco::Entity::Meta> object creation near the top of the
class, setting the database table name:

  tangram => { table => 'guitar', }