1 Introduction
2 Installation
3 Usage
3.1 Initializing a Package
3.2 Embedding Documentation
3.3 Viewing Embedded Documentation
3.4 Setup (Compiling)
3.5 Updating PLane T Development Links
3.6 Making a PLane T Archive for Upload
3.7 Easter Egg
4 Known Issues
5 History
6 Legal
Version: 1:8

McFly Tools: Developer Tools for Racket

Neil Van Dyke

1 Introduction

This release is for intrepid alpha testers only. Alpha testers should be familiar with Racket and with software development in general. Bug reports and enhancement requests 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.

  • Programmatically updates "info.rkt" files to add any missing definitions. (This uses the progedit package.)

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

2 Installation

To install McFly Tools, evaluate:

(require (planet neil/mcfly-tools))

3 Usage

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 “raco setup: nothing to do” in response to raco setup -P with development links, which breaks McFly Tools. This was fixed on 2012-06-12 in commit af9d11bfce8673fa2d72cec77651ba771e1971fe.

3.1 Initializing a Package

When first starting to use McFly Tools for a package, you may wish to do this:
  1. 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".)

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

  3. Look at "info.rkt", especially all the “;; TODO:” comments. Make any necessary changes. Perhaps most importantly for now:
    • 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:

      (define mcfly-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 them.

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

  5. If you don’t want to have your implementation and documentation in "main.rkt", but raco mcfly init 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:

    "main.rkt"

    #lang racket/base
    (require "foo.rkt")
    (provide (all-from-out "foo.rkt"))
    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.2 Embedding Documentation

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

3.3 Viewing Embedded Documentation

To view embedded documentation, do:
  raco mcfly view
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 raco mcfly view, so this will also work:
  raco mcfly
Note: If you’re running this from Emacs M-x compile, such as with a Unix command line like:
  cd /home/bob/foo && raco mcfly
and you find that sometimes the page isn’t opened in your browser because of a race condition with process killing, you might need to add a delay:
  cd /home/bob/foo && raco mcfly && sleep 1

3.4 Setup (Compiling)

You can update PLaneT development links and run raco setup for your package with:
  raco mcfly setup
Or:
  raco mcfly s

3.5 Updating PLaneT Development Links

You can update PLaneT development links with the command:
  raco mcfly planet-links
Or:
  raco mcfly pl
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.
raco mcfly planet-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.6 Making a PLaneT Archive for Upload

To make a PLaneT archive for upload to the PLaneT server and sharing with the world:
  1. Check that you have added the appropriate version history entry to your (doc history ...) form. (Note that McFly Tools does not currently check this, so check manually.)

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

  3. Do a final raco mcfly setup and double-check that whatever tests you have still run.

  4. Do:
      raco mcfly planet-archive
    Or:
      raco mcfly pa

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

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

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

3.7 Easter Egg

  raco mcfly marty

4 Known 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.

5 History

6 Legal

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.