Finishing moves: jsonic

Intro­ducing the package server

During the setup for these tuto­rial projects, we had to install the beautiful-racket package from the command line like so:

This was our first use of the Racket package server. The package server lives at pkgs.racket-lang.org. The server is a shared Racket resource with three roles:

If we pass a local direc­tory path to raco pkg install, it will install the modules in that direc­tory as a package. But if we pass it a package name (like beautiful-racket) then raco pkg install will contact the online package server to discover the loca­tion of the source repo for that package (often on GitHub). Once it finds the repo, it down­loads the source from that loca­tion and installs it.

Behind the scenes, the package server handles other house­keeping as well, in coop­er­a­tion with the local raco tools. For instance, the package server moni­tors the source repos of each package for changes (e.g., new commits) and asso­ciates a checksum with each update. That way, if we later do this:

raco pkg will coop­erate with the package server to figure out whether we have the most recent version of beautiful-racket (in which case it will do nothing) or if there’s a more recent version (in which case it will down­load and install it).

The package server is also used by raco pkg to resolve missing depen­den­cies. For instance, recall our list of jsonic depen­den­cies:

Suppose a user tries to install jsonic and doesn’t have any of these pack­ages installed. In that case, raco pkg uses the package server to get the source for each package and install it, as if the user had done this manu­ally:

Other package-server bene­fits

Package server prereq­ui­sites

We’re going to make our jsonic language avail­able through the package server (though not perma­nently).

To get started with the package server, we first need to do two things:

Creating an entry on the package server

First we’ll log in to pkgs.racket-lang.org with our email and pass­word.

Then we’ll click the green Add your own button in the grey box at the top of the page:

This will show us a form:

We need to edit three fields: the package name, the package descrip­tion, and the repos­i­tory.

The package name is at the top. This will be the name used by those installing the package with raco pkg install.  + Or by other devel­opers, if they list our language as a depen­dency in their own pack­ages. The package name does not need to be the same as our source repo. Nor does it need to be the same as the collec­tion name, which we explic­itly set in the "info.rkt" file as jsonic.

Because others may be trying this tuto­rial, let’s make our package name jsonic-xyz, where xyz is our initials or other distinct iden­ti­fier—that way, we won’t collide with someone else’s test package. Click the field under­neath Package Name and enter the name:

Then we move to the Package Descrip­tion field and option­ally enter a short descrip­tion, which will appear on the main package listing:

Then we move to the Repos­i­tory field and enter our Git repo, which will be some­thing like username/jsonic:

We click the blue Save changes button. As confir­ma­tion, the package server shows us the new entry for jsonic-xyz:

And if we go back to the top page of pkgs.racket-lang.org, we’ll see our new package listed among the others:

That’s all we need. Now our package will be avail­able to anyone who wants to use it.

Installing our language via the package server

First, let’s remove our locally installed jsonic proto­type, so it doesn’t conflict with the one we’re about to install:

Now let’s rein­stall jsonic from the package server. From the command line, we install our package using its new name:

This time, raco pkg install will consult the package server to get the loca­tion of the jsonic-xyz source. It will down­load and install it. After that, we should be able to look up jsonic in the docu­men­ta­tion, or use #lang jsonic, just as we could before.

If we ever want to move or rename the source repo, however, we’ll have to return to the package server inter­face to update the Source loca­tion for our package.

In the real world ...

We’d stop here. Once our package is on the package server, there’s no ongoing main­te­nance. Within a day or so, the docu­men­ta­tion would appear at docs.racket-lang.org/jsonic-xyz.

Over time, we can update the package simply by pushing new commits to our jsonic repo. We don’t have to notify the package server—it will auto­mat­i­cally detect the change and pass it along to any users who invoke raco pkg update.

Deleting our work

Once we’re satis­fied that we’ve got the hang of the package server, let’s erase our tracks. First, from the command line, let’s remove our local instal­la­tion of the package we installed from the package server:

Then we log in again to pkgs.racket-lang.org and click on the entry for jsonic-xyz.

Before we delete jsonic-xyz, let’s notice that while we were gone, the package server peeked into our Git repo and made a list of depen­den­cies and modules. This is part of how the package server helps manage updates of installed pack­ages.

We’ll click the blue Edit this package button at the top of the screen to get back to the package-editing page:

Finally, we click the red Delete package button at the bottom, and confirm the dele­tion. This perma­nently scrubs jsonic-xyz from the package server.

By the way

We won’t be using the package server for the remaining tuto­rials. The process of turning a language into a package, and uploading it to the package server, is essen­tially the same for any language.

For those who want an alter­na­tive to a Git-hosted repo, it’s also possible to deploy a package without using Racket’s package server.