Difference between revisions of "ValidationFAQ"

From The Battle for Wesnoth Wiki
(Overview of 1.15.x's validation support)
(Validating an add-on: This isn't ready for use yet)
Line 24: Line 24:
  
 
{{DevFeature1.15|?}} Can be done using the Wesnoth engine's ''--validate-addon'' option.
 
{{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:
 
Needs more documentation, but for now check:

Revision as of 21:17, 7 September 2020

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 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.
  • 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:

Obsolete 2011 tool ==

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.

General questions about validation

  • 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

  • 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

  • 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

  • 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

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 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)