Perl 6
Smart Linking: Revision 9

Smart Links refer to a special syntax used in the test suite which connect a particular part of a test script with a specific part of the Perl 6 specification.

A smart link looks like this in a test script:

 # L<S29/Math::Trig>

After submitting this to the Subversion repository, after a few minutes a cron script will update a copy of the Specification which references these links. See the Math::Trig spec for an example.

Smart links are especially valuable for a language that is in development. The help answer these important questions:

  • Has this feature been tested? If you don't see references to tests from the spec, there's a possibility the feature is not only untested, but unimplemented!
  • Are there duplicates tests for this feature? If you see more than one test script linked in one place, it's possible there are duplicate tests, and the tests suite can be simplified.
  • Is there a spec for this feature? On the other hand, if you find a test without a smart link, it may simply not have one yet, or the feature may be unspec'ed. It was discovered that the basic function "say" did not have a formal definition through this kind of review.

Smart Linking Status

As of September 11th, 2006, 263 test scripts have at least one smart link, but 349 do not.
Help wanted!

How to get the Test Suite

The test suite currently lives in the pugs repository, run the following from your parrot download and you'll have the full test suite.

´╗┐cd languages/perl6 && make t/spec

How to help with smart linking.

To help with this, you mostly just some motivation to help, and commit access
to the pugs tree. Ask for it on #perl6 if you don't have it.

perldoc util/ explains the details. Here are practical tips to get started.

1. Review the complete list of files with no smart links:

grep -RL 'L<' t/* | $PAGER

2. Pick a directory that needs work. For example, in builtins/lists, 11 files need updated now.

cd builtins/lists

3. Open these files

$EDITOR `grep -L 'L<' *.t`

4. Add at least one appropriate smart link, possibly using the online specification as a reference. The nice thing about working in one directory at one time, is that all of the smart links in the directory me be similar.

5. Check your smart links

~/pugs/util/ --check *.t

Hopefully, you'll get some useful debugging feedback if there is a problem. You can also specify --fast if you don't want to update your local copy of Synopses at every run.

6. Commit your work!
Usually this is svk commit or svn commit.

Ask for help on the #perl6 IRC channel if you get stuck.

A simple script to help

Somewhere in your path create a file called check_links and chmod +x it:

/pugs/util/ --syn-dir ~/pugs/docs/Perl6/Spec --check $@

Then anywhere you want to test a set of files you can simply run

check_links --missing *.t

And it will list out all the files in the current directory with a .t extension that are missing smart links. This makes it much easier to work in a directory of tests and get a feel for what needs done.

Upload Files

Click "Browse" to find the file you want to upload. When you click "Upload file" your file will be uploaded and added to the list of attachments for this page.

Maximum file size: 50MB

File Name Author Date Uploaded Size

Save Page As

Enter a meaningful and distinctive title for your page.

Page Title:

Tip: You'll be able to find this page later by using the title you choose.

Page Already Exists

There is already a page named XXX. Would you like to:

Save with a different name:

Save the page with the name "XXX"

Append your text to the bottom of the existing page named: "XXX"

Upload Files

Click "Browse" to find the file you want to upload. When you click "Add file" this file will be added to the list of attachments for this page, and uploaded when you save the page.

Add Tags

Enter a tag and click "Add tag". The tag will be saved when you save the page.