Difference between revisions of "Maintenance tools"

From The Battle for Wesnoth Wiki
(Name change)
Line 2: Line 2:
 
are:
 
are:
 
   
 
   
; macroscope: a cross-reference lister, useful for finding unresolved macro and resource-file references.
+
; wmlscope: a cross-reference lister, useful for finding unresolved macro and resource-file references.
  
; upconvert: a utility for porting your old WML to the current version of WML.   
+
; wmllint: a utility for porting your old WML to the current version of WML.   
  
 
You will need a Python interpreter on your system to use these tools.  Linux, *BSD, and Mac OS/X should already have Python installed; for Windows it's a free download
 
You will need a Python interpreter on your system to use these tools.  Linux, *BSD, and Mac OS/X should already have Python installed; for Windows it's a free download
Line 13: Line 13:
  
 
Both tools will require you to supply a <i>directory list</i>.  This is a set of directories containing the WML files you want to work on.
 
Both tools will require you to supply a <i>directory list</i>.  This is a set of directories containing the WML files you want to work on.
== macroscope ==
 
  
The main use for <tt>macroscope</tt> is to find WML macro references without definitions and references to resource files (sounds and images) that don't exist.  These are difficult to spot from in-game because they usually result in silence or a missing image rather than actual broken game logic.  They may happen because of typos in your WML, or because the name of a macro or the location of a resource file changed betweeen versions of the game.
+
== wmlscope ==
  
<tt>macroscope</tt> has many options for changing the reports it generates; the more advanced ones are intended for Wesnoth developers.  Invocations for the most commonly useful reports it generates are included in <i>data/tools/Makefile</i> of the source distribution. Here are some of those reports:
+
The main use for <tt>wmlscope</tt> is to find WML macro references without definitions and references to resource files (sounds and images) that don't exist.  These are difficult to spot from in-game because they usually result in silence or a missing image rather than actual broken game logic.  They may happen because of typos in your WML, or because the name of a macro or the location of a resource file changed betweeen versions of the game.
 +
 
 +
<tt>wmlscope</tt> has many options for changing the reports it generates; the more advanced ones are intended for Wesnoth developers.  Invocations for the most commonly useful reports it generates are included in <i>data/tools/Makefile</i> of the source distribution. Here are some of those reports:
  
 
; make unresolved: Report on unresolved macro calls and resource references.  (This is what you are most likely to want to do).  Note that in the current version this report works for mainline but still contains some false positives (warnings about bad references that aren't actually bad) when you are checking UMC.  The path-resolution logic is being worked on.
 
; make unresolved: Report on unresolved macro calls and resource references.  (This is what you are most likely to want to do).  Note that in the current version this report works for mainline but still contains some false positives (warnings about bad references that aren't actually bad) when you are checking UMC.  The path-resolution logic is being worked on.
Line 25: Line 26:
 
; make collisions: Report on duplicate resource files.
 
; make collisions: Report on duplicate resource files.
  
For more advanced users, or those who want to understand what the canned Makefile invocations are doing, here is a summary of <tt>macroscope</tt>'s options. Some of the more advanced options will require you to understand  
+
For more advanced users, or those who want to understand what the canned Makefile invocations are doing, here is a summary of <tt>wmlscope</tt>'s options. Some of the more advanced options will require you to understand  
 
[http://docs.python.org/lib/re-syntax.html Python regular expressions].
 
[http://docs.python.org/lib/re-syntax.html Python regular expressions].
  
Line 41: Line 42:
 
; --extracthelp:              Extract help from macro definition comments.
 
; --extracthelp:              Extract help from macro definition comments.
  
Note: in 1.3.3 and later version, this tool has been renamed '''wmlscope'''.
+
Note: in 1.3.2 and earlier versions, this tool was named '''macroscope'''.
 
 
== upconvert ==
 
  
<tt>upconvert</tt> is a tool for migrating your WML to the current version.  It handles two problems:
+
== wmllint ==
  
* Resource files and macro names may change between versions of the game. <tt>upconvert</tt> knows about these changes and will tweak your WML to fit where it can.
+
<tt>wmllint</tt> is a tool for migrating your WML to the current version. It handles two problems:
  
* Between 1.2.x and 1.3.1 the terrain-coding system used in map files underwent a major change. It changed again in a minor way between 1.3.1 and 1.3.2. <tt>upconvert</tt> will translate your maps for you, unless you use custom terrains in which case you will have to do it by hand.
+
* Resource files and macro names may change between versions of the game. <tt>wmllint</tt> knows about these changes and will tweak your WML to fit where it can.
  
<tt>upconvert</tt> does not currently do anything about terrain codes found outside of maps, in terrain filters and the like; you will have to change those by hand.  This may be fixed in a future version.
+
* Between 1.2.x and 1.3.1 the terrain-coding system used in map files underwent a major change. It changed again in a minor way between 1.3.1 and 1.3.2.  <tt>wmllint</tt> will translate your maps for you, unless you use custom terrains in which case you will have to do it by hand.
  
<tt>upconvert</tt> takes a directory-path argument specifying the WML directories to work on.  It will modify any cfg and map files under those directories that need to be changed.  Here is a summary of its options:
+
<tt>wmllint</tt> takes a directory-path argument specifying the WML directories to work on.  It will modify any cfg and map files under those directories that need to be changed.  Here is a summary of its options:
  
 
; -h, --help:                Emit a help message and quit.
 
; -h, --help:                Emit a help message and quit.
Line 75: Line 74:
 
# If the messages look good, run without --dryrun; the old content will be left in backup files with a -bak extension.
 
# If the messages look good, run without --dryrun; the old content will be left in backup files with a -bak extension.
 
# Eyeball the changes with the --diff option.
 
# Eyeball the changes with the --diff option.
# Use macroscope, with a directory path including the Wesnoth mainline WML, to check that you have no unresolved references.
+
# Use wmlscope, with a directory path including the Wesnoth mainline WML, to check that you have no unresolved references.
 
# Test the conversion.
 
# Test the conversion.
 
# Use either --clean to remove the -bak files or --revert to undo the conversion.
 
# Use either --clean to remove the -bak files or --revert to undo the conversion.
  
Note: in 1.3.3 and later versions this tool has been renamed '''wmllint'''.
+
Note: in 1.3.2 and earlier versions this tool was named '''upconvert'''.

Revision as of 19:16, 30 May 2007

The Wesnoth source code distribution includes a couple of tools intended to help authors maintain campaigns, faction & unit packs, and other WML resources. These are:

wmlscope
a cross-reference lister, useful for finding unresolved macro and resource-file references.
wmllint
a utility for porting your old WML to the current version of WML.

You will need a Python interpreter on your system to use these tools. Linux, *BSD, and Mac OS/X should already have Python installed; for Windows it's a free download from http://www.python.org. You will also need to know how to run command-line tools on your system.

Both these tools are under very active development, so it is recommended that you do a Subversion checkout of the Wesnoth source code in order to get the latest version before proceeding.

Both tools will require you to supply a directory list. This is a set of directories containing the WML files you want to work on.

wmlscope

The main use for wmlscope is to find WML macro references without definitions and references to resource files (sounds and images) that don't exist. These are difficult to spot from in-game because they usually result in silence or a missing image rather than actual broken game logic. They may happen because of typos in your WML, or because the name of a macro or the location of a resource file changed betweeen versions of the game.

wmlscope has many options for changing the reports it generates; the more advanced ones are intended for Wesnoth developers. Invocations for the most commonly useful reports it generates are included in data/tools/Makefile of the source distribution. Here are some of those reports:

make unresolved
Report on unresolved macro calls and resource references. (This is what you are most likely to want to do). Note that in the current version this report works for mainline but still contains some false positives (warnings about bad references that aren't actually bad) when you are checking UMC. The path-resolution logic is being worked on.
make all
Report all macro and resource file references, not just unresolved ones.
make collisions
Report on duplicate resource files.

For more advanced users, or those who want to understand what the canned Makefile invocations are doing, here is a summary of wmlscope's options. Some of the more advanced options will require you to understand Python regular expressions.

-h, --help
Emit a help message and quit
-c, --crossreference
Report resolved macro references (implies -w 1)
-C, --collisions
Report duplicate resource files
-d, --deflist
Make definition list. (This one is for campaign server maintainers.)
-e regexp, --exclude regexp
Ignore files matching the specified regular expression.
-f dir, --from dir
Report only on macros defined under dir
-l, --listfiles
List files that will be processed
-r ddd, --refcount=ddd
Report only on macros with references in exactly ddd files.
-u, --unresolved
Report unresolved macro references
-w, --warnlevel
Set to 1 to warn of duplicate macro definitions
--forced-used reg
Ignore reference count 0 on names matching regexp
--extracthelp
Extract help from macro definition comments.

Note: in 1.3.2 and earlier versions, this tool was named macroscope.

wmllint

wmllint is a tool for migrating your WML to the current version. It handles two problems:

  • Resource files and macro names may change between versions of the game. wmllint knows about these changes and will tweak your WML to fit where it can.
  • Between 1.2.x and 1.3.1 the terrain-coding system used in map files underwent a major change. It changed again in a minor way between 1.3.1 and 1.3.2. wmllint will translate your maps for you, unless you use custom terrains in which case you will have to do it by hand.

wmllint takes a directory-path argument specifying the WML directories to work on. It will modify any cfg and map files under those directories that need to be changed. Here is a summary of its options:

-h, --help
Emit a help message and quit.
-d, --dryrun
List changes but don't perform them.
-o, --oldversion
Specify version to begin with (not usually needed).
-v, --verbose
Set verbosity; more details below.
-c, --clean
Clean up -bak files.
-D, --diff
Display diffs between unconverted and unconverted files (only on Linux, *BSD or Mac).
-r, --revert
Revert the conversion from the -bak files.

The verbosity option works like this:

-v
lists changes.
-v -v
warns of maps already converted.
-v -v -v
names each file before it's processed.
-v -v -v -v
shows verbose parse details (developers only).

The recommended procedure is this:

  1. Run it with --dryrun first to see what it will do.
  2. If the messages look good, run without --dryrun; the old content will be left in backup files with a -bak extension.
  3. Eyeball the changes with the --diff option.
  4. Use wmlscope, with a directory path including the Wesnoth mainline WML, to check that you have no unresolved references.
  5. Test the conversion.
  6. Use either --clean to remove the -bak files or --revert to undo the conversion.

Note: in 1.3.2 and earlier versions this tool was named upconvert.