Maintenance tools

Материал из Wesnoth Life Wiki
Перейти к: навигация, поиск

Исходники Wesnoth содержат набор инструментов, предназначенных для облегчения работы над кампаниями, фракциями, наборами юнитов и другими WML ресурсами. А именно:

wmlscope
a cross-reference lister, useful for finding unresolved macro and resource-file references (штука, полезная для нахождения используемых, но не определённых макросов и ресурсов).
wmllint
утилита проверки корректности WML синтаксиса и для перевода старого WML в WML текущей версии.
wmlindent
утилита для приведения WML в единый стиль форматирования.

Для использования этих инструментов Вам потребуется установленный интерпретатор Python 2. На Linux, *BSD, и Mac OS/X он уже установлен; для Windows его можно бесплатно скачать с http://www.python.org. Кроме того, Вы должны знать как использовать инструменты командной строки на вашей системе.

Все эти три инструмента потребуют от Вас указать список каталогов - набор папок, в которых хранятся WML файлы, которые Вы хотите обработать.

Эта страница предназначена для пользователей. Поговорить об ограничениях и устройстве этих инструментов вы можете тут [1].

Примечание для пользователей Windows: Эти инструменты запускаются из командной строки (Command Line). Её можно получить нажав Пуск - Выполнить (Win+R) и введя "cmd" или "command" в зависимости от вашей версии Windows.

Пример использования:

python wmllint путь\к\файлам
python wmlindent путь\к\файлам

Или даже так:

"C:\Program Files\Python2.4\python.exe" data\tools\wmllint --dryrun data\core data\{multiplayer,themes} data\campaigns 

(Вам нужно указать полный путь к интерпретатору Python в том случае, если у Вас не настроена корректно переменная PATH в вашем окружении). Сперва Вы указываете путь к интерпретатору Python6 затем через пробел путь к скрипту, который Вы хотите запустить, и, наконец, путь к папке или файлу, который Вы хотите обработать.


Удобный способ запуска wmllint на Linux (Debian Lenny) и Windows (Xp) в сравнении, Linux:

python2 /usr/share/games/wesnoth/data/tools/wmllint --dryrun /usr/share/games/wesnoth/data/core ~/.wesnoth1.7/data/add-ons/A_Simple_Campaign 1>wmllint-run.log 2>wmllint-err.log

Я разместил все эти комманды в файле с именем

wmllint_dryrun_ASC.sh

и выполняю их, запуская его через шелл (=терминал, консоль и т.д.), перейдя предварительно в каталог с этим файлом:

bash wmllint_dryrun_ASC.sh

Команда python2 должна быть известна оболочке Debian. Путь к скрипту сообщает интерпретатору какой скрипт надо выполнить. --dryrun: одна из опций wmllint, об этом ниже. Путь к файлам ядра нужен чтобы сказать wmllint например об определённых юнитах ядра, после чего идёт genm к аддону, который нужно проверить. Последние две комманды записывают лог выполнения команды и сообщения об ошибках в соответствующие файлы в той же папке, где запущен скрипт. Windows, по сути то же самое, что и в команде для оболочки Linux, Вам нужно только изменить пути к файлам:

E:\Python26\python.exe E:\Programme\Wesnoth_1.8_svn\data\tools\wmllint --dryrun E:\Programme\Wesnoth_1.8_svn\data\core E:\Programme\Wesnoth_1.8_svn\userdata\data\add-ons\A_Simple_Campaign 1>wmllint-run.log 2>wmllint-err.log

Сохраните этот файл с именем своё_имя.bat. В таком случае двойной клик на файле будет его запускать. Так как мой PATH не настроен, я указываю полный путь к интерпретатору. Если в вашем пути встречаются пробелы - возьмите его в кавычки:

"C:\Programs\Battle for Wesnoth 1.8\data\tools\wmllint"

Помните, что Вам не нужны одновременно все команды или пути. Если Вы получите ошибку "unknown command", значит python не установлен на вашей системе или у вас не настроен путь. В таком случае обратитесь к руководству по вашей системе, где будет описано как его установить или добавить в путь.

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 between versions of the game.

wmlscope also checks macro invocations for consistency. It will complain if a macro is called with the wrong number of arguments. In most cases it can deduce information about the type of the literal expected to be passed to a given macro argument by looking at the name of the formal.

Type Meanining Formals requiring this type Literals of this type
side a single side number SIDE, *_SIDE, SIDE[0-9] a numeric or "global"
numeric a numeric integer literal SIDE, X, Y, RED, GREEN, BLUE, TURN, PROB, LAYER, TIME, *_SIDE, *NUMBER, *AMOUNT, *COST, *RADIUS, *_X, *_Y, *_INCREMENT, *_FACTOR, *_TIME, *_SIZE, DURATION \-?[0-9]+
percentage a percentage *PERCENTAGE a numeric or 0\.[0-9]+
position a single x,y coordinate POSITION, *_POSITION, BASE -?[0-9]+,-?[0-9]+
span a set of coordinates or coordinate ranges *_SPAN a numeric, position or ([0-9]+\-[0-9]+,?|[0-9]+,?)+
alliance a set of side numbers SIDES, *_SIDES a span, or the empty string
range an attack range RANGE "melee" or "ranged"
alignment an alignment keyword ALIGN "lawful" or "neutral" or "chaotic"
types a set of unit types TYPES a shortname, name, or anything that contains spaces and matches no other type
terrain_pattern a set of terrain codes to filter ADJACENT*, TERRAINLIST*, *TERRAIN_PATTERN, RESTRICTING a terrain_code or name
terrain_code a single terrain code, perhaps with overlay TERRAIN*, *TERRAIN a shortname or (\*|[A-Z][a-z]+)\^([A-Z][a-z\\|/]+\Z)?
shortname a terrain code or a short, capitalized variable name [A-Z][a-z][a-z]?
name a name or identifier NAME, VAR, IMAGESTEM, ID, FLAG, *_NAME, *_ID, NAMESPACE, BUILDER, *_VAR anything without spaces that matches no other type
optional_string a string value (may be empty) ID_STRING, NAME_STRING, DESCRIPTION, IPF a string, or the empty string
string a nonempty string not matching any of the preceding types STRING, TYPE, TEXT, *_STRING, *_TYPE, *_TEXT a shortname, a name, a stringliteral, or anything that contains spaces and matches no other type
stringliteral a string in doublequotes or a translated string ".*" or _.* but not _[a-z].*
image an image path, perhaps with image path functions *IMAGE, PROFILE [A-Za-z0-9{}.][A-Za-z0-9_/+{}.-]*\.(png|jpg)(?=(~.*)?)
sound a music or sound filename MUSIC, SOUND string ending with ".wav" or ".ogg"
filter WML filter FILTER any non-quoted string containing "="
WML arbitrary WML fragment WML, *_WML any non-quoted string containing "=", or the empty string
affix a prefix, suffix, or infix for a variable name AFFIX, *AFFIX, POSTFIX, ROTATION a shortname or name, or the empty string
any anything *VALUE, [ARS][0-9] anything

If the actual argument is a macro call {.*}, then it matches any formal Otherwise, if the formal has an identifiable type, wmlscope will complain if the actual literal does not match it.

The argument type check only works in macro calls that fit on a single line.

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; also report macro argument-type mismatches. (This is what you are most likely to want to do).
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
--force-used reg
Ignore reference count 0 on names matching regexp
--extracthelp
Extract help from macro definition comments.

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 also performs various sanity-checking operations, reporting:

  • unbalanced tags
  • strings that need a translation mark and do not have them
  • strings that have a translation mark and should not
  • translatable strings containing macro references
  • filter references by description= (id= in 1.5) not matched by an actual unit
  • abilities or traits without matching special notes, or vice-versa
  • consistency between recruit= and recruitment_pattern= instances
  • double space after punctuation in translatable strings.
  • unknown races or movement types in units

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.
-v, --verbose
Set verbosity; more details below.
-c, --clean
Clean up -bak files.
-D, --diff
Show diffs between unconverted and unconverted files.
-r, --revert
Revert the conversion from the -bak files.
-n, --nolift
Suppress lifting, do sanity checks only

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.

Additionally, wmllint tries to locate a spell checker on your system and spell-checks storyline and message strings. It will work automatically with either aspell, myspell, or ispell provided you have the enchant.py Python library installed.

wmlindent

Call with no arguments to filter WML on standard input to reindented WML on standard output. If arguments are specified, they are taken to be files to be re-indented in place; interrupting will be safe, as each reindenting will be done to a copy that is atomically renamed when it's done. This code never modifies anything but blank lines and leading and trailing whitespace on non-blank lines.

The indent unit is four spaces. Absence of an option to change this is deliberate; the purpose of this tool is to prevent style wars, not encourage them.

If you don't apply this tool to your own WML, the mainline-campaign maintainers will do it when and if your code is accepted into the tree.

Note: This tool does not include a parser. It will produce bad results on WML that is syntactically unbalanced. Unbalanced double quotes that aren't part of a multiline literal will also confuse it. You will receive warnings if there's an indent open at end of file or if a closer occurs with indent already zero; these two conditions strongly suggest unbalanced WML.