Smart Linking


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:

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.

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

S02-builtin_data_types/array_extending.t
S02-builtin_data_types/array_mmd.t
S02-builtin_data_types/array_ref.t
S02-builtin_data_types/assigning-refs.t
S02-builtin_data_types/catch_type_cast_mismatch.t
S02-builtin_data_types/flattening.t
S02-builtin_data_types/lists.t
S02-builtin_data_types/nested_arrays.t
S02-builtin_data_types/nested_pairs.t
S02-builtin_data_types/subscripts_and_context.t
S02-literals/listquote-whitespace.t
S02-literals/string-interpolation.t
S02-literals/underscores.t
S02-magicals/config.t
S02-magicals/dollar-underscore.t
S02-magicals/pid.t
S02-magicals/progname.t
S02-whitespace_and_comments/pod-in-multi-line-exprs.t
S03-junctions/autothreading.t
S03-junctions/basic.t
S03-operators/binding-closure.t
S04-blocks-and-statements/pointy-rw.t
S04-statements/for-scope.t
S04-statements/for_with_only_one_item.t
S04-statements/lazy.t
S04-statements/map-and-sort-in-for.t
S05-grammar/namespace.t
S05-grammar/ws.t
S05-mass/stdrules.t
S05-match/arrayhash.t
S05-match/blocks.t
S05-match/non-capturing.t
S05-modifier/sameaccent.t
S06-advanced_subroutine_features/recurse.t
S06-advanced_subroutine_features/wrapping.t
S06-currying/assuming-and-mmd.t
S06-signature/errors.t
S06-signature/passing-arrays.t
S06-signature/passing-hashes.t
S06-signature/slurpy-params.t
S06-signature/sub-ref.t
S10-packages/export.t
S10-packages/import.t
S10-packages/require_and_use.t
S12-attributes/inheritance.t
S12-class/namespaced.t
S12-methods/topic.t
S12-role/namespaced.t
S16-io/basic-open.t
S29-list/mutating_listops.t
S29-list/uniq.t