Difference between revisions of "ValidationFAQ"

From The Battle for Wesnoth Wiki
(Created page with 'Validation is a special tool, developed by Sytyi, GSoC 2011 participant. This is a special page to answer validation-specified questions, since using of it is not so obvious. =…')
 
(→‎Manually validating a mainline campaign: Note that SCHEMA_SHOULD_SKIP_THIS is no longer required)
 
(7 intermediate revisions by 4 users not shown)
Line 1: Line 1:
−
Validation is a special tool, developed by Sytyi, GSoC 2011 participant.
+
== The validation tool built in to the Wesnoth engine ==
  
−
This is a special page to answer validation-specified questions, since using of it is not so obvious.
+
{{DevFeature1.15|?}} The Wesnoth engine's ''--validate'' option makes Wesnoth run the validation instead of playing the game. It's run automatically on the mainline campaigns as part of the continuous-integration builds, via the ''utils/travis/schema_validation.sh'' script.
  
−
= General questions about validation =
+
The rules for validating WML are defined by [[SchemaWML]] files in the ''data/schema/'' directory.
−
* When is validation done? - Validation is done while config fle is parsing. Parser calls validator when opens|closes tag or reads a key.
 
−
* Can I create my own validation, based on special idea? - Yes. Parser calls methods of an Abstract Base Class, so you can write your own realization and override methods. If you are interested - [[ValidationDesign]] can be useful for you. Good luck!
 
−
* What realizations are already written? - At this moment schema validation only.
 
  
−
= General questions about schema validation  =
+
=== Manually validating a mainline campaign ===
−
* What is the main idea of schema validation? - There is a special schema, describing allowed WML. At this moment of time next information is stored: Name of the tag, his minimal required and maximum allowed number of occasions (in context of his parent); List of keys allowed to use in this tag, each key has its name, type and default value (or is mandatory key); List of allowed child tags.
 
−
* What are the possible errors? - You can receive next errors:
 
−
** This tag|key is not allowed here.
 
−
** Required M tags, found X < M tags.
 
−
** Allowed N tags, found X > N tags.
 
−
** Missing mandatory key.
 
−
** Key has wrong value.
 
−
* Where can I read an error? - There are two modes of validation: default and strict. While default, errors arre printed in validation log. While strict (wgich can be enabled with --strict-validation) every validation error is treated as fatal, and creates a WML exception which stops reading of the file and prints error message either to console or on the screen (depends on file. I.e. GUI WML errors stop loading wesnoth and are printed to console).
 
  
−
== I'm a WML contibutor ==
+
To run it manually on a mainline campaign, validate data/_main.cfg with the appropriate defines.
−
* How can I know that my WML was validated - Preparing of validation needs a lot of time. At this moment of time only one toplevel tag [gui] can be validated. Only C++ developer can enable validation and he needs schema file.  
 
  
−
== I'm a WML contibutor and I want to help in creating schema ==
+
* wesnoth --validate data/_main.cfg --preprocess-defines=TEST,SCHEMA_SHOULD_SKIP_THIS
−
* Can you tell some about schema in general? - Schema file is build from schema markup using schema_generator tool. Schema markup can be used both in different .cpp files and .schema files. Schema markup from different files is merged. Schema is stored in .cfg file as WML with toplevel [wml_schema]
+
* wesnoth --validate data/_main.cfg --preprocess-defines=TUTORIAL
−
* Where can I read detail info about schema markup format? - [[WML_Annotation_Format]].
+
* wesnoth --validate data/_main.cfg --preprocess-defines=EASY,CAMPAIGN_THE_RISE_OF_WESNOTH,DISABLE_GRAND_MARSHAL
−
* How can I use schema_generator tool? - Run Cmake, Enable option "Enable tools", and run make. Two specific schema tools will be build: schema_generator and schema_validator. You can read about usage of the schema_generator on [[WML_Annotation_Format#Usage_of_the_tool]] Please, specify the input directory and the output file.
+
* wesnoth --validate data/_main.cfg --preprocess-defines=NORMAL,CAMPAIGN_THE_RISE_OF_WESNOTH,DISABLE_GRAND_MARSHAL
−
* How can I test my schema file? - Either read next article in this FAQ, or use schema_validator.
+
* etc
−
./schema_validator -i <input_file> -s <schema_file> Then you will see a lot of error messages. 
 
  
−
== I'm a C++ developer and I want to enable validation in my contributions to engine ==
+
Points to note:
−
* How can I do that? - First, you need to have initial schema file. Second, find all occasions of reading config file and using one of the [http://devdocs.wesnoth.org/parser_8hpp.html read] functions.
+
* These commands may also need ''--userconfig-dir'' and ''--data-dir'' arguments, depending on where you're running the Wesnoth executable from.
−
+
* ''TEST'' validates test scenarios, including the AI demo scenarios and the WML unit tests, and requires ''SCHEMA_SHOULD_SKIP_THIS'' to avoid failing on some tests which check the engine's response to invalid WML. {{DevFeature1.15|14}} This extra define is no longer required to validate tests from the command line.
 +
* Campaigns need a separate validation run for each of their difficulty levels.
 +
* The ''[campaign]extra_defines='' value needs to be added on the command line, for example TRoW uses ''DISABLE_GRAND_MARSHAL''
  
 +
=== Validating an add-on ===
  
−
[[Category:Validation]
+
{{DevFeature1.15|?}} Can be done using the Wesnoth engine's ''--validate-addon'' option.
 +
 
 +
{{DevFeature1.15|4}} The current status as of 1.15.4 is that this tool isn't ready for use yet.
 +
 
 +
Needs more documentation, but for now check:
 +
 
 +
* https://github.com/wesnoth/wesnoth/issues/4223 only validates when the cache is rebuilt
 +
* https://github.com/wesnoth/wesnoth/issues/4224 no feedback on typos
 +
* https://github.com/wesnoth/wesnoth/issues/4225 the GUI starts even when just validating
 +
 
 +
=== Validating the GUI ===
 +
 
 +
The GUI WML code is automatically validated every time you launch the game, but it can also be validated manually with the following command-line:
 +
 
 +
* wesnoth --validate data/gui/_main.cfg --use-schema=data/schema/gui.cfg
 +
 
 +
As with validating a campaign, you may also need ''--data-dir'' and ''--userconfig-dir''.
 +
 
 +
=== Validating a schema ===
 +
 
 +
Since WML schemas are themselves a form of WML, they can also be validated with the tool. You can use a method similar to GUI above and just point to schema.cfg instead, but the following command-line enables some additional checks such as ensuring all types you use have been defined:
 +
 
 +
* wesnoth --validate-schema data/schema/gui.cfg
 +
 
 +
As with validating a campaign, you may also need ''--data-dir'' and ''--userconfig-dir''.
 +
 
 +
[[Category:Validation]]

Latest revision as of 04:09, 15 June 2021

The validation tool built in to the Wesnoth engine

(Version 1.15.? and later only) The Wesnoth engine's --validate option makes Wesnoth run the validation instead of playing the game. It's run automatically on the mainline campaigns as part of the continuous-integration builds, via the utils/travis/schema_validation.sh script.

The rules for validating WML are defined by SchemaWML files in the data/schema/ directory.

Manually validating a mainline campaign

To run it manually on a mainline campaign, validate data/_main.cfg with the appropriate defines.

  • wesnoth --validate data/_main.cfg --preprocess-defines=TEST,SCHEMA_SHOULD_SKIP_THIS
  • wesnoth --validate data/_main.cfg --preprocess-defines=TUTORIAL
  • wesnoth --validate data/_main.cfg --preprocess-defines=EASY,CAMPAIGN_THE_RISE_OF_WESNOTH,DISABLE_GRAND_MARSHAL
  • wesnoth --validate data/_main.cfg --preprocess-defines=NORMAL,CAMPAIGN_THE_RISE_OF_WESNOTH,DISABLE_GRAND_MARSHAL
  • etc

Points to note:

  • These commands may also need --userconfig-dir and --data-dir arguments, depending on where you're running the Wesnoth executable from.
  • TEST validates test scenarios, including the AI demo scenarios and the WML unit tests, and requires SCHEMA_SHOULD_SKIP_THIS to avoid failing on some tests which check the engine's response to invalid WML. (Version 1.15.14 and later only) This extra define is no longer required to validate tests from the command line.
  • Campaigns need a separate validation run for each of their difficulty levels.
  • The [campaign]extra_defines= value needs to be added on the command line, for example TRoW uses DISABLE_GRAND_MARSHAL

Validating an add-on

(Version 1.15.? and later only) Can be done using the Wesnoth engine's --validate-addon option.

(Version 1.15.4 and later only) The current status as of 1.15.4 is that this tool isn't ready for use yet.

Needs more documentation, but for now check:

Validating the GUI

The GUI WML code is automatically validated every time you launch the game, but it can also be validated manually with the following command-line:

  • wesnoth --validate data/gui/_main.cfg --use-schema=data/schema/gui.cfg

As with validating a campaign, you may also need --data-dir and --userconfig-dir.

Validating a schema

Since WML schemas are themselves a form of WML, they can also be validated with the tool. You can use a method similar to GUI above and just point to schema.cfg instead, but the following command-line enables some additional checks such as ensuring all types you use have been defined:

  • wesnoth --validate-schema data/schema/gui.cfg

As with validating a campaign, you may also need --data-dir and --userconfig-dir.

Retrieved from "https://wiki.wesnoth.org/index.php?title=ValidationFAQ&oldid=68069"
This page was last edited on 15 June 2021, at 04:09.