1 Using PLane T
2 The PLane T Search Order
3 The planet Command-Line Tool
4 Utility Libraries
5 Developing Packages for PLane T
On this page:
5.1 Write Your Package
5.1.1 Development Links
5.2 Prepare Your Distribution
5.2.1 Arrange Files Into a Directory
5.2.2 Create Documentation [Optional]
5.2.3 Create an "info.ss" File [Optional]
5.3 Build a Distribution Archive
5.4 Determine Your Package’s Backwards-Compatibility
5.5 Submit Your Package
Version: 4.0.2

 

5 Developing Packages for PLaneT

To put a package on PLaneT, or release an upgrade to an already-existing package:

5.1 Write Your Package

PLaneT can distribute whatever programs you write, but keep these guidelines in mind as you write:

5.1.1 Development Links

To aid development, PLaneT allows users to establish direct associations between a particular planet package with an arbitrary directory on the filesystem, for instance connecting the package named by the require line

(require (planet "file.ss" ("my" "mypackage.plt" 1 0)))

to the directory "/home/myname/svn/mypackages/devel/".

These associations are intended to allow developers to use their own directory structures, version control systems, and so on while still being able to use the packages they create as though they were distributed directly by PLaneT. Development links are local to a particular user and repository (but not to a particular MzScheme minor revision).

To establish a development link, use the planet command-line tool:

  planet link myname mypackage.plt 1 0 ~/svn/mypackages/devel

Once you are finished developing a package, you should remove any development links you have established for it, again using the planet command-line tool:

  planet unlink myname mypackage.plt 1 0

You may alternately use the functions add-hard-link and remove-hard-link.

5.2 Prepare Your Distribution

5.2.1 Arrange Files Into a Directory

Make sure that all source files, documentation, etc. that you want to be a part of the package are in a single directory and its subdirectories. Furthermore make sure that nothing else, e.g. unneeded backup files, is in that directory (with the exception that the subdirectories and files CVS or Subversion creates are automatically skipped by the packaging tool).

5.2.2 Create Documentation [Optional]

Use Scribble to write documentation for your package. See Scribble: PLT Documentation Tool for instructions on how to write Scribble documentation.

5.2.3 Create an "info.ss" File [Optional]

If you put a file named "info.ss" in your package’s root directory, the PLaneT system (as well as the rest of the PLT Scheme tool suite) will look in it for descriptive metadata about your package. The PLaneT system looks for certain names in that file:

In addition, PLaneT uses the setup-plt installer to install packages on client machines, so most fields it looks for can be included with their usual effects. In particular, adding a 'name field indicates that the Scheme files in the package should be compiled during installation; it is a good idea to add it.

An example info.ss file looks like this:

  #lang setup/infotab

  (define name "My Application")

  (define blurb

    '("My application runs 60% faster on 20% less peanut "

      "butter. It even shows a fancy graphic!"))

  (define primary-file "my-app.ss")

  (define categories '(system xml))

See the PLT mzc: MzScheme Compiler Manual, chapter 7 for more information on info.ss files.

5.3 Build a Distribution Archive

Use the planet command-line tool in its archive-creation mode to create a planet archive:

  planet create /home/jacob/my-app/

This will create a planet archive named "my-app.plt" in the current directory whose contents are the contents of "/home/jacobm/my-app" and all its subdirectories.

Alternately, you can run make-planet-archive with the name of the directory you’ve prepared as its argument:

(make-planet-archive "/home/jacob/my-app/")

This function will build a packaged version of your directory and return the path to that package. The path will always be a file named "X.plt", where "X" is the name of the directory you gave to make-planet-archive, located in that same directory.

You can now test that your archive file works as intended using the planet command-line tool in its install mode:

  planet fileinject <owner> <path to your .plt file> <maj> <min>

installs the specified file into your local PLaneT cache as though it had been downloaded from the PLaneT server with the given owner name and major and minor versions. After you run this command, you can require your package on your local machine using

(require (planet <file> (<owner> <.plt file name without path> <maj> <min>)))

to verify everything works. After you do so, you can use

  planet remove <owner> <.plt file name without path> <maj> <min>

to remove the test package from your local cache. (Not removing it is safe as long as you use the same name and version numbers the package will have on the PLaneT server; otherwise you may experience problems.)

5.4 Determine Your Package’s Backwards-Compatibility

If you are updating a previously-released package, you must decide whether your package is a backwards-compatible change or not. A rule of thumb is to remember that modules written to work with the previously-released version of your package should unmodified with the new package. This means that at a minimum, a backwards compatible update should:

A backwards-compatible upgrade may, however:

Currently these rules are guidelines only, but in the future some or all of them may be enforced programmatically. Ultimately, though, no technical device can precisely capture what it means for a package to be backwards-compatible with a previous version, so you should use your best judgment.

5.5 Submit Your Package

Go to the central PLaneT package repository web page and click on the link marked "contribute a package / log in" in the upper-right-hand corner. If you have not yet created an account, then do so on that page by providing your name, a user name, an email address, and a password and then responding to the confirmation message delivered to the email address you provide.

Once you have an account, then if this is a new package then upload it using the "Contribute a package" section in your user account page. If this is a package update then click "update this package" next to its name in the "Manage your packages" section of your user account page, then upload the .plt file and indicate on the form whether your update is backwards-compatible with the prior version or not.