_Distributing Packages with PLaneT_ ----------------------------------- To put a package on PLaneT, or release an upgrade to an already-existing package: 1. PREPARE 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 allowed). For instance, in the following directory tree, my-app/ is set up appropriately: home/ ... jacob/ ... my-app/ doc.txt my-app.ss graphic-for-my-app.png private/ implementation.ss There are no strict requirements for what sorts of files can go in your package, but for it to work well with PLT Scheme's module system you should arrange your Scheme code into modules. 2. CREATE INFO.SS AND DOC.TXT FILES [OPTIONAL] If you put a file named info.ss in your package's root directory, the PLaneT system will look in it for descriptive metadata about your package. The PLaneT system looks for certain names in that file: The _'blurb field_ If present, the blurb field should contain a list of XHTML fragments encoded as x-expressions (see the xml collection for details) that PLaneT will use as a short description of your project. This field is also used by the Help Desk. The _'categories field_ If present, the categories field should be a list of symbols corresponding to the categories under which this package should be listed. The valid categories are: Symbol Description ------ ----------- devtools Development Tools net Networking and Protocols media Graphics and Audio xml XML-Related datastructures Data Structures and Algorithms io Input/Output and Filesystem scientific Mathematical and Scientific system Hardware/Operating System-Specific Tools ui Textual and Graphical User Interface metaprogramming Metaprogramming Tools planet PLaneT-Related misc Miscellaneous If you put symbols other than these the categories field, they will be ignored. If you put no legal symbols in the categories field or do not include this field in your info.ss file, your package will be categorized as "Miscellaneous." The _'doc.txt field_ If present, the doc.txt field should be a string corresponding to the name (without path) of the text documentation file for your package. If this field is the value "doc.txt" and a file called "doc.txt" exists in your package's root directory, it will be used as the online documentation visitors to the planet.plt-scheme.org website will be able to read. The _'html-docs field_ If present, this field should be a list of strings representing subdirectories of your package. These directories will be used by Help Desk as HTML documentation for your package. See _Creating Help Desk Documentation in HTML format_ for more information on how to useful HTML Help Desk documentation. The _'homepage field_ If present, the URL field should be a string corresponding to a URL for the package. PLaneT provides this link with the description of your package on the main PLaneT web page. The _'primary-file field_ If present, the primary-file field should be a string corresponding to the name (without path) of the main Scheme source file of your package. PLaneT will direct casual users of your library to require this file. The _'version field_ If present, the version field should describe the version number of this code that should be presented to users (e.g., "0.15 alpha"). This field does not override or in any way interact with your package's package version number, which is assigned by PLaneT, but may be useful to users. 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 probably a good idea to add it. An example info.ss file looks like this: (module info (lib "infotab.ss" "setup") (define name "My Application") (define blurb (list "My application runs 60% faster on 20% less peanut " "butter. It even shows a fancy graphic!")) (define primary-file "my-app.ss") (define doc.txt "doc.txt") (define categories '(system xml))) See the PLT mzc: MzScheme Compiler Manual, chapter 7 for more information on info.ss files. The other special file PLaneT looks for in the root directory of your package is doc.txt. Its contents should be documentation for your package. Its contents will be available as a link on your package's listing on the PLaneT web page. 3. BUILD A .PLT FILE Use the planet command-line tool in its archive-creation mode to create a planet archive: planet --create-archive /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 the function make-planet-archive from the util.ss module in the planet collection 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 .plt file works as intended using the planet command-line tool in its install mode: planet --file will install the specified .plt 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 ( <.plt file name without path> ))) to verify everything works. After you do so, you can use planet --remove <.plt file name> 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 official PLaneT server; otherwise you may experience problems.) 4. SUBMIT THE PACKAGE E-mail the .plt file you built to jacobm+planet@plt-scheme.org If the package is an upgrade to a prior package, then tell me so and tell me whether or not this package is backwards-compatible with the package it's upgrading. Also tell me what PLT Scheme version this package is intended for. There's no particular format for this message; the system isn't automated yet so I'll just be reading these and processing them by hand. Once I've added your package to the repository, I'll e-mail you back and tell you the require-line users will need to type in to get it. WARNING: It's very important that packages you say are backwards-compatible with the prior version, at a minimum contain all the same modules and provide all the same names the prior version did. If you do not, programs that use your package will break on some systems.