Smart Linking

eric.hodges@hidden — Tue, 16 Dec 2008 19:16:44 -0000

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.

Smart Links Example

A smart link looks like this in a test script:

# L

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.

Benefits of Smart Links

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

(generated using smartlinks.pl --check /.t from within ~/pugs/t/spec)

As of December 16th, 2008 we now have info: 659 smartlinks found and 0 broken in 411 test files (60 test files had no links).

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/smartlinks.pl 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/smartlinks.pl --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:

#!/bin/bash
~/pugs/util/smartlinks.pl --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.

Test files still needing links

(generated using smartlinks.pl --check --wiki /.t from within ~/pugs/t/spec)

Perl 6: Smart Linking