OpenInteract Packages - Managing and distributing applications
This document describes the packaging system in OpenInteract.
A package is all the code, SQL structures, configuration information and anything else necessary to implement functionality in OpenInteract.
In OpenInteract, packages implement the actual application functionality. OpenInteract handles the storage interface (e.g., putting your objects in a database), dispatches URL requests to your objects (this is called handling an action), security, authentication and authorization, and session management.
Applications need to define objects, which is how an application handles its state. It also needs to define how the objects are to be manipulated, which users can access them and how functionality is exposed to the user (by way of a URL to action mapping).
Obviously, OpenInteract comes with tools to install, uninstall and query currently installed packages. This greatly simplifies the task of creating, testing and distributing your application.
What goes into a package? In general, you will find:
spops.perl, both of which are discussed further below.
package.conffile along with the SQL installation class.
oi_managewill create a preliminary POD file for you which documents your package. You are strongly encouraged to fill in the blanks and add meaningful detail along with any other necessary files to let people know what functionality your package provides.
oi_manage script included with OpenInteract will create a basic
package skeleton for you. Here's an example:
oi_manage --package=mypackage --base_dir=/tmp/OpenInteract \ create_skeleton
Will create the following files:
mypackage # Main directory mypackage/package.conf # Basic package configuration (name, ...) mypackage/MANIFEST # List of files in package mypackage/MANIFEST.SKIP # Regexes to skip when creating MANIFEST mypackage/conf # Configuration directory mypackage/conf/spops.perl # Persistent object(s) configuration mypackage/conf/action.perl # Action(s) configuration mypackage/data # Package data/security directory mypackage/doc # Documentation directory mypackage/doc/mypackage.pod # Starter documentation mypackage/doc/titles # Map documentation name to subject mypackage/struct # Package table definition directory mypackage/template # Template directory mypackage/script # Tools program directory mypackage/html # Static html directory mypackage/html/images # Image directory mypackage/OpenInteract # Object hierarchy directory mypackage/OpenInteract/Handler # Package handler directory
You will normally need to edit/add the following:
mypackage/package.conf # Add name, version, author information mypackage/MANIFEST # Add names of distribution files mypackage/conf/spops.perl # Describe the objects your package uses mypackage/conf/action.perl # Map URLs to handlers in your package mypackage/data # Specify the initial data and security mypackage/struct # Describe the tables used to store your objects mypackage/template # HTML to display and manipulate your objects mypackage/OpenInteract # Optional Perl modules defining object behavior mypackage/OpenInteract/Handler # Manipulate objects for desired functionality mypackage/doc/mypackage.pod # Last but not least, tell the world about it
By the way, the MANIFEST file can be created automatically. (Perl is great.) Here's how:
>> cd /path/to/mypackage >> perl -MExtUtils::Manifest -e 'ExtUtils::Manifest::mkmanifest()'
That's it! If you have an old 'MANIFEST' file in the directory it will be copied to 'MANIFEST.bak'. Also note that files matching patterns in the 'MANIFEST.SKIP' file will not be included.
Now that you've created a package already, you've seen most of its
contents. (The ones you care about, anyway.) However, each package is
OpenInteract::Package object -- a normal SPOPS object.
OpenInteract maintains a registry of installed packages in a central
location. (To find the file, go to the
conf/ directory of your base
OpenInteract installation. The
package_install.gdbm holds the
This registry includes meta information about all currently installed
packages -- author, install date, version, etc. You can browse the
information using a command-line tool (named
oi_manage) to see what
is currently installed, along with querying the information to find
dependencies, authors, etc.
Properties of the OpenInteract::Package object:
Name of package
Version of package
Author(s) of package, full name and email address is used for each
entry; the list should be sorted in order of importance
Web address with more information about the package
Two or three paragraphs about the package
Notes about this particular installation of a package.
Name of class which will get called by
install the SQL structures, data and security necessary for this package.
Date this package was last updated
User who updated this package
Date this package was installed
User who installed this package
Chris Winters <email@example.com>
Christian Lemburg <firstname.lastname@example.org>