3 Developing Packages
To create a package, first make a directory for your package and select its name, ‹package›:
mkdir ‹package›
Next, link your development directory to your local package repository:
raco pkg install --link ‹package›
Optionally, enter your directory and create a basic "info.rkt" file:
The "info.rkt" file is not necessary if you have no dependencies, but you may wish to create it to simplify adding dependencies in the future. (Note that this "info.rkt" is for the package, not for a collection; definitions such as scribblings or raco-commands work only in a collection’s "info.rkt".)
Next, inside the ‹package› directory, create directories for the collections and modules that your package will provide. For example, the developer of tic-tac-toe package that provides games/tic-tac-toe/main and data/matrix libraries might create directories and files like this:
After your package is ready to deploy, choose either GitHub Deployment or Manual Deployment.
3.1 GitHub Deployment
First, create a free account on GitHub, then create a repository for your package. After that, publish your package source as:
github://github.com/‹user›/‹package›/‹branch›
Typically, ‹branch› will be master, but you may wish to use different branches for releases and development.
Whenever you
git push
your changes will automatically be discovered by those who used your package source when they use raco pkg update.
3.2 Manual Deployment
By default, raco pkg create generates a Zip archive. For more options, refer to the raco pkg create documentation. If you want to generate an archive through some other means, simply archive what you made in the first part of this section. For more formal details, refer to the package definition.
Alternatively, you can deploy your package by publishing it on a URL you control. If you do this, it is preferable to create an archive from your package directory first:
raco pkg create ‹package›
And then upload the archive and its checksum to your site:
scp ‹package›.zip ‹package›.zip.CHECKSUM your-host:public_html/
Now, publish your package source as:
http://your-host/~‹user›/‹package›.zip
Whenever you want to provide a new release of a package, recreate and reupload the package archive (and checksum). Your changes will automatically be discovered by those who used your package source when they use raco pkg update.
3.3 Helping Others Discover Your Package
By using either of the above deployment techniques, anyone will be able to use your package by referring to your package source. However, they will not be able to refer to it by a simple name until it is listed on a package name resolver.
If you’d like to use the official package name resolver, browse to https://pkg.racket-lang.org/manage/upload and upload a new package. You will need to create an account and log in first.
You only need to go to this site once to list your package. The server will periodically check the package source you designate for updates.
If you use this server, and use GitHub for deployment, then you will never need to open a web browser to update your package for end users. You just need to push to your GitHub repository, then within 24 hours, the official package name resolver will notice, and raco pkg update will work on your user’s machines.
3.4 Naming and Designing Packages
Although of course not required, we suggest the following system for naming and designing packages:
Packages should not include the name of the author or organization that produces them, but be named based on the content of the package. For example, data-priority-queue is preferred to johns-amazing-queues.
Packages that provide an interface to a foreign library or service should be named the same as the service. For example, cairo is preferred to Racket-cairo or a similar name.
Packages should not generally contain version-like elements in their names, initially. Instead, version-like elements should be added when backwards incompatible changes are necessary. For example, data-priority-queue is preferred to data-priority-queue1. Exceptions include packages that present interfaces to external, versioned things, such as sqlite3 or libgtk2.
A version declaration for a package is used only by other package implementors to effectively declare dependencies on provided features. Such declarations allow raco pkg install and raco pkg update to help check dependencies. Declaring and changing a version is optional, and package name resolvers ignore version declarations; in particular, a package is a candidate for updating when its checksum changes, independent of whether the package’s version changes or in which direction the version changes.
Packages should not combine large sets of utilities libraries with other functionality. For example, a package that contain many extensions to the "racket" collection, like "racket/more-lists.rkt" and "racket/more-bools.rkt" should not also contain complete applications, as other packages interested in the "racket/more-bools.rkt" library will not wish to depend on in such application.
Packages should generally provide one collection with a name similar to the name of the package. For example, libgtk1 should provide a collection named "libgtk". Exceptions include extensions to existing collection, such as new data-structures for the "data" collection, DrRacket tools, new games for PLT Games, etc.
Packages are not allowed to start with plt, racket, or planet without special approval from PLT curation.