Difference between revisions of "ValidationFAQ"

From The Battle for Wesnoth Wiki
(→‎Validating an add-on: This isn't ready for use yet)
(→‎Manually validating a mainline campaign: Note that SCHEMA_SHOULD_SKIP_THIS is no longer required)
 
(4 intermediate revisions by 2 users not shown)
Line 17: Line 17:
 
Points to note:
 
Points to note:
 
* These commands may also need ''--userconfig-dir'' and ''--data-dir'' arguments, depending on where you're running the Wesnoth executable from.
 
* These commands may also need ''--userconfig-dir'' and ''--data-dir'' arguments, depending on where you're running the Wesnoth executable from.
−
* ''TEST'' validates 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.
+
* ''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.
 
* 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''
 
* The ''[campaign]extra_defines='' value needs to be added on the command line, for example TRoW uses ''DISABLE_GRAND_MARSHAL''
Line 33: Line 33:
 
* https://github.com/wesnoth/wesnoth/issues/4225 the GUI starts even when just validating
 
* https://github.com/wesnoth/wesnoth/issues/4225 the GUI starts even when just validating
  
−
== Obsolete 2011 tool ====
+
=== Validating the GUI ===
  
−
Validation is a special tool, developed by Sytyi, GSoC 2011 participant.
+
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:
  
−
This is a special page to answer validation-specified questions, since using of it is not so obvious.
+
* wesnoth --validate data/gui/_main.cfg --use-schema=data/schema/gui.cfg
  
−
=== General questions about validation ===
+
As with validating a campaign, you may also need ''--data-dir'' and ''--userconfig-dir''.
−
* 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  ===
+
=== Validating a schema ===
−
* 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 ====
+
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:
−
* 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-schema data/schema/gui.cfg
−
* 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]
 
−
* Where can I read detail info about schema markup format? - [[WML_Annotation_Format]].
 
−
* 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.
 
−
* How can I test my schema file? - Either read next article in this FAQ, or use schema_validator.
 
−
./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 ====
+
As with validating a campaign, you may also need ''--data-dir'' and ''--userconfig-dir''.
−
If you are interested how that works, [[ValidationDesign]] can be useful for you.
 
−
* 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. 
 
−
Create your validator object , catch exception (bad schema, or file not read), and send validator as a parameter to read(). You can specify whether you need strict validation or not. Id strict validation was not enabled errors will be put in "validation" log.
 
−
 
 
−
==== Future of validation ====
 
−
If you are interesting in future of validation, please read (here will be links to the forum, to the non-written yet threads about new schema markup format and putting schema info inside file to be validated)
 
−
==== Your questions ====
 
−
Put your own questions here, please.
 
−
 
 
−
 
 
−
With best wishes - Sytyi (nsytyi@gmail.com)
 
  
 
[[Category:Validation]]
 
[[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.