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.
(require (planet neil/mcfly-tools))
The following subsections tell how to use McFly Tools for particular problems.
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 initThis 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. 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.
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.
- 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:
#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".
You embed documentation with doc forms. See the documentation for McFly Runtime, which is what actually formats the documentation.
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.)
Check "info.rkt", especially that the version number in mcfly-planet is correct for this upload.
Do a final raco mcfly setup and double-check that whatever tests you have still run.
- Do:raco mcfly planet-archiveOr:raco mcfly pa
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 raco planet fileinject 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.
raco mcfly marty
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.
- PLaneT 1:9 —
Made parse-planet-symbol-string/ignore-equals more permissive. (Thanks to Asumu Takikawa.)
This Scribble file generated by this version of McFly Tools now depends on McFly Runtime version 1:2 rather than 1:1, to be more permissive about PLaneT package names.
Removed documentation note about raco setup -P being briefly broken in Racket Git a month earlier.
- PLaneT 1:8 —
- PLaneT 1:7 —
- PLaneT 1:6 —
Trying to prevent install-time running.
- PLaneT 1:5 —
Added first shot at usage documentation.
Added raco mcfly init.
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 —
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.
- PLaneT 1:3 —
Fixed one problem that might have caused raco mcfly to run at install time.
Enabled adding repositories to "info.rkt".
Added documentation note about recent Racket nightly builds breaking McFly Tools.
- PLaneT 1:2 —
Now, mcfly-subtitle isn’t added to "info.rkt" if mcfly-title is defined.
- PLaneT 1:1 —
raco mcfly planet-archive now sets force-package-building? to #f rather than #t. (Thanks to Robby Findler and Eli Barzilay.)
- PLaneT 1:0 —
Initial alpha-quality release. Not for general use.
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.