Changes between Version 21 and Version 22 of ValidationSimple

Timestamp:

Oct 14, 2014, 10:24:36 AM (10 years ago)

Author:

davea

Comment:

--

ValidationSimple

@@ +1 @@
+[[PageOutline]]
 = Developing a custom validator =
-To create a validator using the BOINC framework, you must supply three functions:
+
+To create a validator, you must supply three functions:
 
 {{{
 extern int init_result(RESULT& result, void*& data);
 }}}
-This takes a result, reads its output file(s), parses them into a memory structure, and returns (via the 'data' argument) a pointer to this structure. It returns:
+This takes a result, reads its output file(s), parses them into a memory structure,
+and returns (via the 'data' argument) a pointer to this structure.
+The return value is:
 
  * Zero on success,
- * ERR_OPENDIR if there was a transient error, e.g. the output file is on a network volume that is not available. The validator will try this result again later.
- * Any other return value indicates a permanent error. Example: an output file is missing, or has a syntax error. The result will be marked as invalid.
+ * ERR_OPENDIR if there was a transient error, e.g. the output file is on a network volume that is not available.
+  The validator will try this result again later.
+ * Any other return value indicates a permanent error.
+  Example: an output file is missing, or has a syntax error.
+  The result will be marked as invalid.
+
+To locate and open the result's output files, use
+[wiki:BackendUtilities utility functions] such as '''get_output_file_path()''' and '''try_fopen()'''
+(see example below).
 
 {{{
@@ -16 +27 @@
 );
 }}}
-This takes two results and their associated memory structures. It returns (via the 'match' argument) true if the two results are equivalent (within the tolerances of the application).
+This takes two results and their associated memory structures.
+It returns (via the 'match' argument) true if the two results are equivalent
+(within the tolerances of the application).
 
 {{{
@@ -23 +36 @@
 This frees the structure pointed to by data, if it's non-NULL.
 
-You must link these functions with the files validator.cpp, validate_util.cpp, and validate_util2.cpp. The result is your custom validator.
+You must link these functions with the files validator.cpp, validate_util.cpp, and validate_util2.cpp.
+The result is your custom validator.
 
 If for some reason you need to access the WORKUNIT in your init_result() etc. functions:
@@ -45 +59 @@
 
 == Example ==
-Here's an example in which the output file contains an integer and a double. Two results are considered equivalent if the integer is equal and the doubles differ by no more than 0.01.
-
-This example uses [wiki:BackendUtilities utility functions] get_output_file_path() and try_fopen().
+Here's an example for an application
+whose output file contains an integer and a double.
+Two results are considered equivalent if the integers are equal and the doubles differ by no more than 0.01.
 
 {{{
@@ -101 +115 @@
 }
 }}}
+
+== Testing your validator ==
+
+While you're developing a validator,
+it's convenient to run it in "standalone mode",
+i.e. run it manually against particular output files.
+BOINC provides a test harness that lets you do this:
+
+ * In boinc/sched/, copy '''makefile_validator_test''' to your own file, say '''makefile_vt'''.
+ * Edit this makefile, changing VALIDATOR_SRC to refer to the .cpp file
+   containing your init_result(), compare_result(), and cleanup_result() functions.
+ * Do '''make -f makefile_vt'''.
+
+This creates a program '''validator_test'''.
+Do
+{{{
+validator_test file1 file2
+}}}
+to test your code against the given output files.
+It will show the result of each function call.
+
+Notes:
+ * Currently this assumes that results have a single output file.
+   If you need this generalized, let us know.