▼PLane  T:   Automatic Package Distribution
►6 Developing Packages for PLane  T
On this page:
6.1 Write Your Package
6.1.1 Development Links
6.2 Prepare Your Distribution
6.2.1 Arrange Files Into a Directory
6.2.2 Create Documentation [Optional]
6.2.3 Create an "info.rkt" File [Optional]
6.3 Build a Distribution Archive
6.4 Determine Your Package’s Backwards-Compatibility
6.5 Submit Your Package
  top  ← prev  up  next → 

6 Developing Packages for PLaneT

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

6.1 Write Your Package

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

  • Organize your code into modules. Since the PLaneT client is integrated into the require form, it works best if your code is arranged into modules.

  • When one module in your program depends on another, it is best to require it using the relative-file-name form rather than the planet require form. For instance, if your program contains files primary.rkt and helper.rkt where primary.rkt requires helper, use the form

    (require "helper.rkt")

    instead of

    (require (planet "helper.rkt" ("username" "packagename.plt" 1 0)))

    in files that will also be a part of the package.

6.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.rkt" ("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 Racket minor revision).

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

  raco 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:

  raco planet unlink myname mypackage.plt 1 0

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

6.2 Prepare Your Distribution

6.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 meta-subdirectories and files Git/Subversion/CVS uses are automatically skipped by the packaging tool).

6.2.2 Create Documentation [Optional]

Use Scribble to write documentation for your package. See Scribble Documentation for macros that ensure proper bindings and version numbers in documentation for PLaneT packages, and Scribble: The Racket Documentation Tool for instructions on how to write Scribble documentation.

When testing your documentation, set up a development link and use

raco setup -P <owner> <package-name> <maj> <min>

with arguments based on the development link to build and test your documentation.

Note: Always use this-package-in in for-label bindings when documenting PLaneT packages, and always use the bindings in planet/scribble rather than scribble/manual. These macros automatically produce planet-based module paths with appropriate version numbers. Other require subforms and Scribble declarations may refer to the wrong version of a package, or may not be recognized as part of a PLaneT package at all when documentation is produced.

6.2.3 Create an "info.rkt" File [Optional]

If you put a file named "info.rkt" in your package’s root directory, the PLaneT system (as well as the rest of the Racket 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 raco setup 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 Racket files in the package should be compiled during installation; it is a good idea to add it.

An example info.rkt file looks like this:

#lang info
(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.rkt")
(define categories '(system xml))

See "info.rkt" File Format for more information on "info.rkt" files.

6.3 Build a Distribution Archive

  1. So that the next step can find for-label documentation in your own package, first set up a development link (if it is not already set), using
      raco planet link <owner> pkg.plt> <maj> <min> <path-to-files>
    This step is not necessary if your package has no documentation.

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

      raco planet create /home/jacobm/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/jacobm/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.

  3. Remove the development link from the first step (assuming you added one) using
      raco planet unlink <owner> <packagename.plt> <maj> <min>

  4. Now test that your archive file works as intended using the planet command-line tool in its install mode:
      raco planet fileinject <owner> <path to .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> <maj> <min>)))

    to verify everything works.

  5. Finally, use
      raco planet remove <owner> <.plt file name> <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.)

6.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:

  • Contain all the same Racket source files in that the previous version contained in directories intended for public access

  • In each public file, provide at least all the bindings that the previous version provided

  • For each name provided with a contract (see Contracts), provide it with a contract that is at least as permissive as the previous contract

A backwards-compatible upgrade may, however:

  • Change any behavior that reasonable consumers of your package would not consider guaranteed (e.g., by fixing bugs or improving the efficiency of operations).

  • Remove files in clearly-marked private sections. By convention, the contents of any directory called "private" are considered private and should not be relied upon by external users of your package.

  • Extend the set of names exported by a module.

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.

6.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.

  top  ← prev  up  next →