5-Minute Guide to Packaging Your Module

About This Document

Background

The ACS is composed of a set of software components known as packages. Some packages merely provide services to other packages (e.g., the community core routines, or the security and session management routines). Other packages provide a service directly to the end-user (e.g., registration, news, or FAQs); these application packages are known as modules. (Thus every module is a package, but not vice versa.)

In the past, there has never been any sort of official distinction between packages and no system for tracking which files belong to which package, aside from informal documentation. Our goal is to provide a central registry and manager for packages. The benefits:

• Clear ownership and responsibility for individual services.
• A standard process for installing and upgrading packages.
• Independent versioning of packages, so components can be upgraded individually, preserving local changes.
• Standard interfaces (contracts) for interdependent packages, so I won't break your package by changing mine.
• A good interface for installing and configuring ACS.

ACS 3.3 includes an APM that provides a subset of the desired functionality. ACS 3.3 was the last monolithic release of ACS: ACS 4.0 will consist of a set of distinct packages (the address book, the bboard, etc.) which will be individually versionable and upgrading. During the wait for the ACS 4.0 release, package owners can still distribute upgrades to their packages by posting tarballs (.apm files) on software.arsdigita.com. The package manager will automate all this.

So What Do I Have To Do?

1. Register as a site-wide administrator on your web service.

2. Go to the package manager on your server. The URL is http://yourservername/admin/apm/.

3. Click the Add a new package link.

4. Follow the prompts to type in the information for your package. If this is a new package under development, use 0.5 for the initial version. Otherwise, exercise your judgement and choose an appropriate version number. Note that the package URL and version URL are filled in automatically for you.

   Choose your package key with care, as it will be used in the file registration process next.

5. Click Create Package.

6. At this point, your package is created, but no files are yet registered as a part of it. APM enforces a number of conventions with regards to file names and locations that must be followed. Please refer to this table for help in conforming to the conventions. A package must include some of these files, but not all of them depending on your software. Carefully check to make sure that you have moved all the files to their new locations. You can optionally add the files to CVS.

   Your package-root is installation specific and is usually something like /web/yourservername/packages. We will use the address-book table as an example in this table. You should be able to substitute your package key when following the table below. For further information, please consult the APM documentation.

   File Purpose	Convention	Address-Book Example
   Package specification.	package-root/package/package.info (created automatically)	package-root/address-book/address-book.info
   SQL to load the data model.	package-root/package/package-create.sql	package-root/address-book/address-book-create.sql
   SQL to drop the data model	package-root/package/package-drop.sql	package-root/address-book/address-book-drop.sql
   SQL files to upgrade the data model	package-root/package/package/upgrade/	package-root/address-book/upgrade/upgrade-2.0-2.0.1.sql package-root/address-book/upgrade/upgrade-2.0.1-2.1.sql
   Tcl init scripts to be run at server startup (e.g. filter registration)	package-root/package/package-init.tcl	package-root/address-book/address-book-init.tcl
   Tcl scripts that define procedures (e.g. procedures that multiple pages use)	package-root/package/package-procs.tcl	package-root/address-book/address-book-procs.tcl
   User-viewable pages	package-root/package/www/	package-root/address-book/www/
   Admin pages	package-root/package/admin-www/	package-root/address-book/admin-www/
   Documentation	package-root/package/www/doc/	package-root/address-book/www/doc/

   The directory hierarchy might look like this:

   /web/yourservername
     +-- packages (directory)
           +-- address-book (directory)
           |     +-- address-book.html
           |     +-- address-book-procs.tcl
           |     +-- address-book-init.tcl
           |     +-- address-book.info
           |     +-- upgrade (directory)
           |     |     +-- upgrade-2.0-2.0.1.sql
           |     |     +-- upgrade-2.0.1-2.1.sql
           |     +-- www (directory)
           |           +-- index.tcl
           |           +-- records.tcl
           |           +--   ...
           |           +-- admin (directory)
           |                 +-- index.tcl
           |                 +--   ...
           +-- bboard
                 ...
   

7. Now, from the package information page for your package, select Manage File Information. Click the Scan link to have APM scan the package directory. It should provide you with options to add all of your package files. Double check that all of your files are included. If so, confirm the addition.

   If there are any files in your package which the package manager wasn't able to find or if you need to add files later, copy the file into the package directory and click the Manage File Information and Scan link just as before. Your new files should be detected. You can remove files using the file manager. Repeat this step as necessary until you've nailed down all the files in your package.

8. Your package is now installed. You can now toggle the activation status of your package. To toggle the activation status, go to your package's page and select Enable this version of the package. This instructs the request processor to start serving your page. The request processor will automatically translate URLs of the style http://yourserver.com/package/* to read files from package-root/package/www/. However, you will need to restart the server and to run data model scripts yourself before your module will work. At any time you can disable your package and after the server is restarted its URLs will no longer be served.

9. Once you've restarted your server and verified that your package is working, you can Generate a distribution file from your package's information page. This will create a .apm tarball that you can distribute to anyone using the ArsDigita Community System for easy installation.

10. Repeat steps 3 through 9 for each additional package you own.

    And you're done! ACS thanks you.

    And Why Am I Doing This Again?

    Most importantly:
    • So we can keep track of ownership and responsibility the individual components of ACS.
    • So we can release upgrades of individual packages without monolithic ACS releases.
    • To make installation and upgrading of ACS far easier and more automated, especially on client sites where lots of files have been locally modified/customized.
    This things will make ACS much more approachable and desirable to new users, and make it easier for us to keep improving and streamlining ACS.

    ---

    jsalz@mit.edu
    Last modified: Sun Aug 6 01:32:44 EDT 2000