McFly Tools: Developer Tools for Racket

1Introduction

This release is for intrepid alpha testers only. Do not
use this unless you are already comfortable with Racket programming, software
development in general, etc. Use at your own risk! If you somehow incur some
kind of loss due to this software, and you send lawyers after me, I will track
you down, I will come to your house, I will take your dog, and I will give your
dog to a more deserving household, on another continent. Thereafter, once a
year, on Christmas Eve, you will receive a card from your dog, telling you how
much better your dog’s life is now that it is rid of you, and among a better
class of people. This will leave you a broken, lonely person, and probably you
will take up substance abuse. Bug reports and enhancement requests that do not
involve lawyers, however, are welcome.

Privacy/Security Warning: McFly Tools makes frequent
requests to the PLaneT server, and these requests might reveal to the server
the package names of Racket packages that you are working on. So don’t use
McFly Tools for trade-secret packages named secret-social-media-startup-based-on-rocks just yet. Probably this little information leak isn’t a
problem for you, but we mention it on principle. An eventual later version of
McFly Tools will likely improve this situation.

McFly Tools is a collection of developer tools for Racket
programmers, oriented towards supporting and encouraging the sharing of Racket
code libraries as reusable PLaneT packages.

Some things McFly Tools does are:

Supports the embedding of documentation directly in source files,
together with the McFly Runtime package.

Maintains PLaneT development links, based on metadata in "info.rkt", information from the PLaneT server, and current activity using
McFly Tools.

Automates building PLaneT archive files for upload to the PLaneT server.

Creates initial "info.rkt" and "main.rkt" for a project.

Note that McFly Tools is a development tool used only by those who
choose to use it. Packages developed using McFly depend only on the McFly
Runtime package.

2Installation

To install McFly Tools, evaluate: (require(planetneil/mcfly-tools))

3Usage

The following subsections tell how to use McFly Tools for
particular problems.

Note: If using McFly Tools with Racket nightly builds or Git from
shortly prior to 2012-06-13, some versions have an erroneous error of “racosetup:nothingtodo” in response to racosetup-P with development links, which breaks McFly Tools. This was fixed
on 2012-06-12 in commit af9d11bfce8673fa2d72cec77651ba771e1971fe.

3.1Initializing a Package

When first starting to use McFly Tools for a package, you may wish
to do this:

Put any files you already have for the package into a directory.
Let’s say you ultimately want your package to be named “foo,” so you might wish to name the directory "foo". (But you don’t have to name it "foo".)

Go into the directory, and run the command:

raco mcfly init

This does the following:

Creates an "info.rkt" if you don’t already have one in the directory;
or modifies your existing one.

Creates a "main.rkt" if you don’t already have one.

Look at "info.rkt", especially all the “;; TODO: comments. Make any necessary changes. Especially:

At the very least, you’ll need to edit the value for mcfly-planet, to set it to the PLaneT owner name, and to check
that the package name and version are correct. If you don’t yet have a PLaneT
account, you can set the owner to a placeholder that you’re unlikely to forget
to change later, like “myplanetownername” so that the definition might now look like: (definemcfly-planet'myplanetownername/foo:1:0)

If your embedded documentation doc forms will not be in "main.rkt", then change mcfly-start to indicate which file will have the documentation.

If you want to have your implementation and documentation in "main.rkt", and if racomcflyinit just created this file for you, it should contain a skeleton file to get you started. You actually should be able to do racomcflyview now, to view formatted documentation in your Web browser.

If you don’t want to have your implementation and documentation in "main.rkt", but racomcflyinit just created that file for you, then, for ease of PLaneT require forms, you might wish to have a "main.rkt" anyway, that merely re-provides definitions from some other module. For example, if file "foo.rkt" has your implementation, you can edit "main.rkt" to look like:

A reason you might want to do this comes from working with
files from multiple packages at once: many tools, including DrRacket and Emacs,
are easier to navigate when the files you’re editing are named things like "foo.rkt" and "bar.rkt", rather than "main.rkt" and "main.rkt".

Your package is now initialized for McFly Tools, such as it is.

3.2Embedding Documentation

You embed documentation with doc forms. See the documentation for McFly Runtime, which is what actually formats the documentation.

3.3Viewing Embedded Documentation

To view embedded documentation, do:

raco mcfly

This should update PLaneT development links and cause the formatted
documentation to be opened in your Web browser.

(You can actually leave off the subcommand of racomcflyview, so racomcfly will work.

3.4Setup (Compiling)

You can update PLaneT development links and run racosetup for your package with:

raco mcfly setup

(Or racomcflys.)

3.5Updating PLaneT Development Links

You can update PLaneT development links with the command:

raco mcfly planet-links

(Or racomcflypl.)

You may add arguments to that command line for each directory tree
you wish to scan. If you don’t specify any directory trees, the current
directory is used as the start of a tree.

racomcflyplanet-links searches each directory for "info.rkt" files with mcfly-planet in them, determines whether a development link is appropriate (by,
e.g., checking the PLaneT server), and does a series of removals and adds of
PLaneT development links. Development links for paths outside of the directory
trees that are being searched are not removed unless they are overridden by a mcfly-planet in one of the searched trees.

3.6Making a PLaneT Archive for Upload

To make a PLaneT archive for upload to the PLaneT server and sharing with the world:

Check that you have added the appropriate version history entry to your (dochistory...) form. (Note that McFly Tools does not currently check
this, so check manually.)

Check "info.rkt", especially that the version number in mcfly-planet is correct for this upload.

Do a final racomcflysetup and double-check that whatever tests you have still
run.

Do:

raco mcfly planet-archive

(Or racomcflypa.)

Wait a minute for it to finish. If it works, it will
create a staging directory, copy files according to mcfly-files into that directory, adjust PLaneT development links, run the make-planet-archive procedure, clean up the staging directory, re-adjust
PLaneT development links, and leave you with a "packagename.plt" file.

You might want to test installation with use of racoplanetfileinject and manipulating your PLaneT cache and links and such.
McFly Tools doesn’t yet automate this part.

Finally, upload your "packagename.plt" file to the PLaneT server, double-checking the version
before you click the button.

3.7Easter Egg

raco mcfly marty

4Known Issues

McFly Tools is not yet feature-complete, nor fully tested. I’m
hoping that feedback from other people helps prioritize the many things that could be improved.

5History

PLaneT 1:5 — 2012-06-14

Added first shot at usage documentation.

Added racomcflyinit.

Any mcfly-planet automatically added to "info.rkt" may include an inferred a package name.

Any mcfly-files automatically added to "info.rkt" will include Racket files from the immediate directory.

PLaneT 1:4 — 2012-06-14

File "info.rkt" is no longer modified unless there are actual changes
to implement. (No more Emacs complaining that file has changed out from under
it when contents are the same.

Each entry added to "info.rkt" is now preceded by a blank line.

Tests fixed.

PLaneT 1:3 — 2012-06-13

Fixed one problem that might have caused racomcfly to run at install time.

Now, mcfly-subtitle isn’t added to "info.rkt" if mcfly-title is defined.

Documentation changes.

PLaneT 1:1 — 2012-06-11

racomcflyplanet-archive now sets force-package-building? to #f rather than #t. (Thanks to Robby Findler and Eli Barzilay.)

PLaneT 1:0 — 2012-06-11

Initial alpha-quality release. Not for general use.

6Legal

Copyright 2012 Neil Van Dyke. This program is Free Software; you can
redistribute it and/or modify it under the terms of the GNU Lesser General
Public License as published by the Free Software Foundation; either version
3 of the License, or (at your option) any later version. This program is
distributed in the hope that it will be useful, but without any warranty;
without even the implied warranty of merchantability or fitness for a
particular purpose. See http://www.gnu.org/licenses/ for details. For
other licenses and consulting, please contact the author.