follow-up: trailing whitespace
This commit is contained in:
+42
-42
@@ -6,12 +6,12 @@
|
|||||||
* Supporting revisions to NetHack structs via incemental
|
* Supporting revisions to NetHack structs via incemental
|
||||||
* uplifts, rather than incrementing EDITLEVEL and breaking
|
* uplifts, rather than incrementing EDITLEVEL and breaking
|
||||||
* savefile compatibility.
|
* savefile compatibility.
|
||||||
*
|
*
|
||||||
* Here is the contrived example struct we'll use for
|
* Here is the contrived example struct we'll use for
|
||||||
* this document:
|
* this document:
|
||||||
*
|
*
|
||||||
* The old revision: The new revision:
|
* The old revision: The new revision:
|
||||||
*
|
*
|
||||||
* struct mystruct { struct mystruct {
|
* struct mystruct { struct mystruct {
|
||||||
* int field1; int field1;
|
* int field1; int field1;
|
||||||
* int field2; int field2;
|
* int field2; int field2;
|
||||||
@@ -20,14 +20,14 @@
|
|||||||
* }; int newfielda;
|
* }; int newfielda;
|
||||||
* int newfieldb;
|
* int newfieldb;
|
||||||
* };
|
* };
|
||||||
*
|
*
|
||||||
* Steps (using mystruct as an example name)
|
* Steps (using mystruct as an example name)
|
||||||
*
|
*
|
||||||
* 1. Paste an exact copy of the struct declaration as it is/was
|
* 1. Paste an exact copy of the struct declaration as it is/was
|
||||||
* in the previous revision into include/revision.h, shrouded by
|
* in the previous revision into include/revision.h, shrouded by
|
||||||
* #if defined(MYSTRUCT_REV0), and tack a '_rev0' suffix onto the
|
* #if defined(MYSTRUCT_REV0), and tack a '_rev0' suffix onto the
|
||||||
* name of the struct. For example,
|
* name of the struct. For example,
|
||||||
*
|
*
|
||||||
* #if defined(MYSTRUCT_REV0)
|
* #if defined(MYSTRUCT_REV0)
|
||||||
* struct mystruct_rev0 {
|
* struct mystruct_rev0 {
|
||||||
* int field1;
|
* int field1;
|
||||||
@@ -35,11 +35,11 @@
|
|||||||
* char field3;
|
* char field3;
|
||||||
* long field4;
|
* long field4;
|
||||||
* };
|
* };
|
||||||
*
|
*
|
||||||
* That goes just ahead of this existing placeholder:
|
* That goes just ahead of this existing placeholder:
|
||||||
*
|
*
|
||||||
* #elif defined(XXX_REV0)
|
* #elif defined(XXX_REV0)
|
||||||
*
|
*
|
||||||
* 2. Place a comment ahead of the mystruct_rev0 declaration
|
* 2. Place a comment ahead of the mystruct_rev0 declaration
|
||||||
* that explains what has changed, and why the revision
|
* that explains what has changed, and why the revision
|
||||||
* is required.
|
* is required.
|
||||||
@@ -50,70 +50,70 @@
|
|||||||
* #define MYSTRUCT_REV0
|
* #define MYSTRUCT_REV0
|
||||||
* #include "revision.h"
|
* #include "revision.h"
|
||||||
* #undef MYSTRUCT_REV0
|
* #undef MYSTRUCT_REV0
|
||||||
*
|
*
|
||||||
* 4. In include/savefile.h, add a new prototype for a function
|
* 4. In include/savefile.h, add a new prototype for a function
|
||||||
* to read the previous revision from the savefile, ideally
|
* to read the previous revision from the savefile, ideally
|
||||||
* immediately following the prototype for the current active
|
* immediately following the prototype for the current active
|
||||||
* one that hasn't got the '_rev0' suffix:
|
* one that hasn't got the '_rev0' suffix:
|
||||||
*
|
*
|
||||||
* extern void sfi_mystruct(NHFILE *, struct mystruct *,
|
* extern void sfi_mystruct(NHFILE *, struct mystruct *,
|
||||||
* const char *);
|
* const char *);
|
||||||
* extern void sfi_mystruct_rev0(NHFILE *, struct mystruct_rev0 *,
|
* extern void sfi_mystruct_rev0(NHFILE *, struct mystruct_rev0 *,
|
||||||
* const char *);
|
* const char *);
|
||||||
*
|
*
|
||||||
* 5. Also in include/savefile.h, in the '#if NH_C < 202300L' block,
|
* 5. Also in include/savefile.h, in the '#if NH_C < 202300L' block,
|
||||||
* add an entry below the one that should already exist for the
|
* add an entry below the one that should already exist for the
|
||||||
* struct that hasn't got the '_rev0' suffix:
|
* struct that hasn't got the '_rev0' suffix:
|
||||||
*
|
*
|
||||||
* #define Sfi_mystruct(a,b,c) sfi_rm(a, b, c)
|
* #define Sfi_mystruct(a,b,c) sfi_rm(a, b, c)
|
||||||
* #define Sfi_mystruct_rev0(a, b, c) sfi_mystruct_rev0(a, b, c)
|
* #define Sfi_mystruct_rev0(a, b, c) sfi_mystruct_rev0(a, b, c)
|
||||||
*
|
*
|
||||||
* 6. Also in include/savefile.h, in the '#define sfi(nhfp, dt, tag)'
|
* 6. Also in include/savefile.h, in the '#define sfi(nhfp, dt, tag)'
|
||||||
* generic function definition, add an entry below the one
|
* generic function definition, add an entry below the one
|
||||||
* that should already exist for the struct name that hasn't
|
* that should already exist for the struct name that hasn't
|
||||||
* got the '_rev0' suffix:
|
* got the '_rev0' suffix:
|
||||||
*
|
*
|
||||||
* struct mystruct * : sfi_rm, \
|
* struct mystruct * : sfi_rm, \
|
||||||
* struct mystruct_rev0 * : sfi_rm_rev0, \
|
* struct mystruct_rev0 * : sfi_rm_rev0, \
|
||||||
*
|
*
|
||||||
* 7. Also in include/savefile.h, a little further down in the
|
* 7. Also in include/savefile.h, a little further down in the
|
||||||
* 'Sfi_' macro defininitions, add one below the existing
|
* 'Sfi_' macro defininitions, add one below the existing
|
||||||
* one for the struct without the '_rev0' suffix:
|
* one for the struct without the '_rev0' suffix:
|
||||||
*
|
*
|
||||||
* #define Sfi_mystruct(a,b,c) sfi(a, b, c)
|
* #define Sfi_mystruct(a,b,c) sfi(a, b, c)
|
||||||
* #define Sfi_mystruct_rev0(a, b, c) sfi(a, b, c)
|
* #define Sfi_mystruct_rev0(a, b, c) sfi(a, b, c)
|
||||||
*
|
*
|
||||||
* Only the input 'Sfi_' is required, because the old revision
|
* Only the input 'Sfi_' is required, because the old revision
|
||||||
* will never be written out to a file, only read in from a
|
* will never be written out to a file, only read in from a
|
||||||
* a file, so no 'Sfo_' is needed.
|
* a file, so no 'Sfo_' is needed.
|
||||||
*
|
*
|
||||||
* 8. In include/sfmacros.h, add a new entry below the existing
|
* 8. In include/sfmacros.h, add a new entry below the existing
|
||||||
* entry that exists without the '_rev0' suffix:
|
* entry that exists without the '_rev0' suffix:
|
||||||
*
|
*
|
||||||
* SF_C(struct, mystruct)
|
* SF_C(struct, mystruct)
|
||||||
* SF_C(struct, mystruct_rev0)
|
* SF_C(struct, mystruct_rev0)
|
||||||
*
|
*
|
||||||
* 9. In include/sfprocs.h, add a new SF_PROTO_C entry below the
|
* 9. In include/sfprocs.h, add a new SF_PROTO_C entry below the
|
||||||
* existing entry that already exists without the '_rev0' suffix:
|
* existing entry that already exists without the '_rev0' suffix:
|
||||||
*
|
*
|
||||||
* SF_PROTO_C(struct, mystruct);
|
* SF_PROTO_C(struct, mystruct);
|
||||||
* SF_PROTO_C(struct, mystruct_rev0);
|
* SF_PROTO_C(struct, mystruct_rev0);
|
||||||
*
|
*
|
||||||
* 10. Also in include/sfprocs.h, add a new SF_ENTRY_C entry below the
|
* 10. Also in include/sfprocs.h, add a new SF_ENTRY_C entry below the
|
||||||
* entry that already exists without the '_rev0' suffix:
|
* entry that already exists without the '_rev0' suffix:
|
||||||
*
|
*
|
||||||
* SF_ENTRY_C(struct, mystruct);
|
* SF_ENTRY_C(struct, mystruct);
|
||||||
* SF_ENTRY_C(struct, mystruct_rev0);
|
* SF_ENTRY_C(struct, mystruct_rev0);
|
||||||
*
|
*
|
||||||
* 11. In src/sfbase.c, add a prototype for a 'norm_ptrs' stub function
|
* 11. In src/sfbase.c, add a prototype for a 'norm_ptrs' stub function
|
||||||
* below the entry that already exists without the '_rev0' suffix:
|
* below the entry that already exists without the '_rev0' suffix:
|
||||||
*
|
*
|
||||||
* void norm_ptrs_mystruct(struct mystruct *d_mystruct);
|
* void norm_ptrs_mystruct(struct mystruct *d_mystruct);
|
||||||
* void norm_ptrs_mystruct_rev0(struct mystruct_rev0 *d_mystruct);
|
* void norm_ptrs_mystruct_rev0(struct mystruct_rev0 *d_mystruct);
|
||||||
*
|
*
|
||||||
* 12. Also in src/sfbase.c, add a 'norm_ptrs' stub function below the
|
* 12. Also in src/sfbase.c, add a 'norm_ptrs' stub function below the
|
||||||
* stub function that already exists without the '_rev0' suffix:
|
* stub function that already exists without the '_rev0' suffix:
|
||||||
*
|
*
|
||||||
* void
|
* void
|
||||||
* norm_ptrs_mystruct(struct mystruct *d_mystruct UNUSED)
|
* norm_ptrs_mystruct(struct mystruct *d_mystruct UNUSED)
|
||||||
* {
|
* {
|
||||||
@@ -123,28 +123,28 @@
|
|||||||
* norm_ptrs_mystruct_rev0(struct mystruct_rev0 *d_mystruct_rev0 UNUSED)
|
* norm_ptrs_mystruct_rev0(struct mystruct_rev0 *d_mystruct_rev0 UNUSED)
|
||||||
* {
|
* {
|
||||||
* }
|
* }
|
||||||
*
|
*
|
||||||
* 13. In src/sfstruct.c, add entries to the 'historical' section below the
|
* 13. In src/sfstruct.c, add entries to the 'historical' section below the
|
||||||
* existing entry that doesn't have a '_rev0' suffix. You need an 'sfo_'
|
* existing entry that doesn't have a '_rev0' suffix. You need an 'sfo_'
|
||||||
* entry and an 'sfi_' entry here, because they have to match function
|
* entry and an 'sfi_' entry here, because they have to match function
|
||||||
* pointers in another struct. The 'sfo_' function will not be called
|
* pointers in another struct. The 'sfo_' function will not be called
|
||||||
* from anywhere.
|
* from anywhere.
|
||||||
*
|
*
|
||||||
* historical_sfo_rm,
|
* historical_sfo_rm,
|
||||||
* historical_sfo_rm_rev0,
|
* historical_sfo_rm_rev0,
|
||||||
* ...
|
* ...
|
||||||
* historical_sfi_rm,
|
* historical_sfi_rm,
|
||||||
* historical_sfi_rm_rev0,
|
* historical_sfi_rm_rev0,
|
||||||
*
|
*
|
||||||
* 14. In the C source file where the 'Sfi_' call is made for your struct,
|
* 14. In the C source file where the 'Sfi_' call is made for your struct,
|
||||||
* the current code likely has a line for reading the struct from
|
* the current code likely has a line for reading the struct from
|
||||||
* a file, similar the one shown below for the mystruct example:
|
* a file, similar the one shown below for the mystruct example:
|
||||||
*
|
*
|
||||||
* Sfi_mystruct(nhfp, &svl.mystruct, "mystruct-example");
|
* Sfi_mystruct(nhfp, &svl.mystruct, "mystruct-example");
|
||||||
*
|
*
|
||||||
* That single line will need to modified to become a code block similar
|
* That single line will need to modified to become a code block similar
|
||||||
* to this, so that the uplift function will get called:
|
* to this, so that the uplift function will get called:
|
||||||
*
|
*
|
||||||
* if (!gu.uplift_needed_rev0_to_rev1) {
|
* if (!gu.uplift_needed_rev0_to_rev1) {
|
||||||
* Sfi_mystruct(nhfp, &svl.mystruct, "mystruct-example");
|
* Sfi_mystruct(nhfp, &svl.mystruct, "mystruct-example");
|
||||||
* } else {
|
* } else {
|
||||||
@@ -154,7 +154,7 @@
|
|||||||
* uplift_mystruct_rev0_to_mystruct(&old_mystruct, &svl.mystruct);
|
* uplift_mystruct_rev0_to_mystruct(&old_mystruct, &svl.mystruct);
|
||||||
* }
|
* }
|
||||||
* }
|
* }
|
||||||
*
|
*
|
||||||
* 15. Shortly after the reading of the struct by the 'Sfi_' function,
|
* 15. Shortly after the reading of the struct by the 'Sfi_' function,
|
||||||
* if the newer revision of the struct added some new fields, new code
|
* if the newer revision of the struct added some new fields, new code
|
||||||
* will be needed to initialize the new fields to sane values.
|
* will be needed to initialize the new fields to sane values.
|
||||||
@@ -164,24 +164,24 @@
|
|||||||
* svl.mystruct.newfielda = sanevalue1;
|
* svl.mystruct.newfielda = sanevalue1;
|
||||||
* svl.mystruct.newfieldb = sanevalue2;
|
* svl.mystruct.newfieldb = sanevalue2;
|
||||||
* }
|
* }
|
||||||
*
|
*
|
||||||
* 16. In include/extern.h, add a prototype to the ' ### revision.c ###'
|
* 16. In include/extern.h, add a prototype to the ' ### revision.c ###'
|
||||||
* section for the supporting uplift function:
|
* section for the supporting uplift function:
|
||||||
*
|
*
|
||||||
* extern void uplift_mystruct_rev0_to_mystruct(struct mystruct_rev0 *,
|
* extern void uplift_mystruct_rev0_to_mystruct(struct mystruct_rev0 *,
|
||||||
* struct mystruct *);
|
* struct mystruct *);
|
||||||
*
|
*
|
||||||
* 17. Add the uplift function to src/revision.c. It needs to do
|
* 17. Add the uplift function to src/revision.c. It needs to do
|
||||||
* field-by-field copies of the fields that exist in the old
|
* field-by-field copies of the fields that exist in the old
|
||||||
* revision and the new revision. For now, it likely needs to
|
* revision and the new revision. For now, it likely needs to
|
||||||
* be handcrafted using your knowledge of the struct's old
|
* be handcrafted using your knowledge of the struct's old
|
||||||
* and new revisions.
|
* and new revisions.
|
||||||
*
|
*
|
||||||
* Be sure that any new fields present in the newer revision
|
* Be sure that any new fields present in the newer revision
|
||||||
* of the struct get set to sane values or initialized to
|
* of the struct get set to sane values or initialized to
|
||||||
* zero. Do whatever suits those fields best, based on your
|
* zero. Do whatever suits those fields best, based on your
|
||||||
* knowledge of the struct.
|
* knowledge of the struct.
|
||||||
*
|
*
|
||||||
* void
|
* void
|
||||||
* uplift_mystruct_rev0_to_mystruct(struct mystruct_rev0 *rev0,
|
* uplift_mystruct_rev0_to_mystruct(struct mystruct_rev0 *rev0,
|
||||||
* struct mystruct *rev1)
|
* struct mystruct *rev1)
|
||||||
@@ -190,12 +190,12 @@
|
|||||||
* rev1->field2 = rev0->field2;
|
* rev1->field2 = rev0->field2;
|
||||||
* rev1->field3 = rev0->field3;
|
* rev1->field3 = rev0->field3;
|
||||||
* rev1->field4 = rev0->field4;
|
* rev1->field4 = rev0->field4;
|
||||||
*
|
*
|
||||||
* rev1->newfielda = 0; // new field
|
* rev1->newfielda = 0; // new field
|
||||||
* rev1->newfieldb = 42; // new field
|
* rev1->newfieldb = 42; // new field
|
||||||
* }
|
* }
|
||||||
*
|
*
|
||||||
*/
|
*/
|
||||||
|
|
||||||
#if defined(MYSTRUCT_REV0)
|
#if defined(MYSTRUCT_REV0)
|
||||||
#ifdef DEMO_UPLIFTS
|
#ifdef DEMO_UPLIFTS
|
||||||
|
|||||||
+3
-3
@@ -13,7 +13,7 @@ boolean revision_increment(
|
|||||||
/*
|
/*
|
||||||
* Revision 1
|
* Revision 1
|
||||||
* We set a flag gu.uplift_needed_rev0_to_rev1 for use by restore routines.
|
* We set a flag gu.uplift_needed_rev0_to_rev1 for use by restore routines.
|
||||||
*
|
*
|
||||||
*/
|
*/
|
||||||
gu.uplift_needed_rev0_to_rev1 = 1;
|
gu.uplift_needed_rev0_to_rev1 = 1;
|
||||||
if (csc[file_critical_byte_count - 1] == 0)
|
if (csc[file_critical_byte_count - 1] == 0)
|
||||||
@@ -26,7 +26,7 @@ boolean revision_increment(
|
|||||||
|
|
||||||
#ifdef DEMO_UPLIFTS
|
#ifdef DEMO_UPLIFTS
|
||||||
|
|
||||||
/* original revision 0 is in include/revision.h */
|
/* original revision 0 is in include/revision.h */
|
||||||
|
|
||||||
/* revision 1 */
|
/* revision 1 */
|
||||||
struct mystruct {
|
struct mystruct {
|
||||||
@@ -54,7 +54,7 @@ void
|
|||||||
read_mystruct(struct mystruct *ms)
|
read_mystruct(struct mystruct *ms)
|
||||||
{
|
{
|
||||||
#ifdef SAVEFILE_REVISION_LEVEL
|
#ifdef SAVEFILE_REVISION_LEVEL
|
||||||
|
|
||||||
#if (SAVEFILE_REVISION_LEVEL == 0)
|
#if (SAVEFILE_REVISION_LEVEL == 0)
|
||||||
Sfi_mystruct(nhfp, ms, "mystruct-example");
|
Sfi_mystruct(nhfp, ms, "mystruct-example");
|
||||||
#elif (SAVEFILE_REVISION_LEVEL == 1)
|
#elif (SAVEFILE_REVISION_LEVEL == 1)
|
||||||
|
|||||||
Reference in New Issue
Block a user