5-Minute Guide to Packaging Your Module

part of the ArsDigita Community System
by Jon Salz and Bryan Quinn

About This Document

This guide is intended primarily for programmers writing new modules for the ArsDigita Community System. It provides instructions for turning an ACS module into an ACS package with the new ACS Package Manager.

Background

From the ACS 4.0 package manager documentation (as of 25 April 2000):
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:

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?

Every package owner (a.k.a. module owner) needs to use the package manager on dev.arsdigita.com to register their packages. The process is very easy. Just
  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 PurposeConventionAddress-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: 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