I've been working on a validation tool that can be used to check WML
trees for unused and unresolved macros, or generate cross-reference
reports on macro usage. This tool has reached production status. You
can find it at data/tools/macroscope, and I'm broadcasting this post
because it opens up some possibilities that may suggest changes an
maintenance policy.
I think the best way for me to explain the capabilities of this tool
is just to show you the contents of the new data/tools/Makefile:
utils-unused:
@echo "Report on unused utility macros"
cd ../..; data/tools/macroscope --crossreference --from data/utils
--refcount 0 data
utils-macros:
@echo "Report on usage of utility macros"
cd ../..; data/tools/macroscope --crossreference --from data/utils data
all-macros:
@echo "Report on usage of all macros"
cd ../..; data/tools/macroscope --crossreference data
unresolved-macros:
@echo "Report on unresolved macro calls"
cd ../..; data/tools/macroscope --unresolved data
For illustrative purposes, here is a utils-unused report on trunk with
most of the lines in the middle elided for brevity
# Macroscope reporting on Sat Apr 7 20:16:29 2007
# Working directory: /home/esr/svn/wesnoth
# Directory path: ['data']
Macro ON_DEATH defined at data/utils/event-utils.cfg:243 is unused
Macro STORE_UNIT_VAR defined at data/utils/utils.cfg:191 is unused
[...]
Macro COLOR_HEAL defined at data/utils/image-utils.cfg:11 is unused
Macro SET_IMAGE_AND_LABEL_PERSISTANT defined at
data/utils/interface-utils.cfg:89 is unused
Macro ADD_GOLD defined at data/utils/deprecated-utils.cfg:34 is unused
One thing that is not obvious from this example is that macroscope
is not limited to cross-referencing WML files in one directory. The
single-argument can be a colon-separated directory list (like the
contents of $PATH).
This means, in particular, that macroscope can be used to check
user-made content as well -- in fact, it will handle any collection
of WML directories downloaded from anywhere.
This capability has a couple of implications.
1) We can, and probably should, require people modifying either
mainline or UMC data to run macroscope on it before committing
or shipping.
2) We can relax about removing obsolete macros. We now have a way
for committers to have high confidence that deletions won't
break anything in mainline, and UMC authors who use macroscope
will now be able to reliably and swiftly detect any such problems
before execution testing.
Here's where it gets more interesting: my next plan for macroscope
is to enable it to do analogous checks on sound and image files,
replacing the rather dodgy find-unused-images and find-unused sounds
scripts.
Suggestions for other sorts of WML validation and report-generation
that might fit in macroscope will be cheerfully accepted. Please bear
in mind that it does not contain a WML parser; the work is done with
regular-expression matching.
For those of you who care about such details, macroscope (a) consists
of about 150 lines of Python, and (b) is in fact named after the
1969 Piers Anthony novel.
--
<a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>
_______________________________________________
Wesnoth-dev mailing list
[email protected]
https://mail.gna.org/listinfo/wesnoth-dev
