Merge remote-tracking branch 'myvanilla/master' into 9.0-savebreaking

This is an enormous merge, but that's to be expected when it covers 1
year and 8 months of vanilla development. Enjoy reading 3000 words of
conflict notes from the almost 1200 conflicts which took nearly a week
to resolve:

COMPLYING WITH UPSTREAM REFORMATS/RENAMES/REFACTORS
- Added NONNULL* declarations to xNetHack-specific functions in extern.h as
  appropriate. Some of the functions did actually check for nulls and produced
  an impossible; turns out gcc will actually catch potential uses of null in
  there AND will error if an argument specified as non-null is checked for null
  within the function, so I removed those checks and impossibles.
- Moved hash functions from hacklib.c to rnd.c because coord_hash relies on
  nethack globals that have been stripped from hacklib .
- Moved current_holidays() to calendar.c.
- Converted xNetHack array[rn2(SIZE(array))] to vanilla's ROLL_FROM(array).
  Replaced a rnd_name macro defined by xNetHack for the same purpose. Left some
  that are unchanged in vanilla or which have a slightly different calculation
  such as rn2(SIZE(array) - 1) in place.
- Formatted monsters.h changes in tune with the guidelines mentioned in 627b40f.
- Discarded xNetHack additions to the controllable verbosity system, since this
  apparently got entirely reverted upstream and no longer exists. If it gets
  added back at some point and I need to reimplement it I will be very cross.
- Updated vanilla's big comment grid documenting room flags in rm.h, but if this
  causes merge conflicts in the future I will probably just ditch it...
- Moved DUMPHTML handling in config.h so that if DUMPHTML is defined at compile
  time but DUMPLOG isn't, DUMPLOG_CORE code will still be compiled in (which
  DUMPHTML relies on).
- Added vanilla's odd FALLTHROUGH before a /* FALLTHRU */ comment where
  observed, but didn't do it comprehensively.
- Inserted xNetHack timeouts MOLDY_CORPSE and FERMENT into timer_is_obj; the
  commit that introduced that macro is older than the last merge, so perhaps
  this was an oversight.
- Changed g[a-z] instance_globals to sv[a-z] instance_globals_saved whenever
  appropriate.
- Added and removed monsters as necessary from the "all other cases" giant
  switch statement in makemon().
- Renamed saved globals in xNetHack code to sv[a-z] as opposed to g[a-z] unsaved
  globals.

NEW ADDITIONS TO THE ENDS OF ARRAYS/ENUMS/ETC
- bigrm-12 "Tea Party" leapfrogs over bigrm-13 "The Great Bridge" to become
  bigrm-14 since vanilla added its own bigrm-12.
- Bump PARANOID_THROW, TER_VISIT, WITHERING & DOOMED, etc to the end of their
  lists rather than sandwiching them between vanilla values, so that the vanilla
  values remain the same in both versions.

COLLIDING ENGRAVING DISPLAY IMPLEMENTATIONS
-
- Moved engraving_to_glyph into a function.
- Deleted secret corridors' eligiblity to show engravings. Vanilla appears to
  have dropped that.

FEATURES WHERE THE UPSTREAM IMPLEMENTATION WAS TAKEN OR XNETHACK CHANGES WERE
DISCARDED
- Took vanilla's implementation of petless conduct (in which the pet counter is
  incremented in initedog() and there is only one place that it needs to be
  decremented because it wasn't a "real" pet).
- Discarded xNetHack-specific HI_BOSS in favor of vanilla's HI_OVERLORD.
- It looks like vanilla commit 4927b2c (putting shop overview names into the
  shclass struct) basically reimplemented xNetHack commit 313d59b, so take their
  implementation.
- Discard xNetHack logic around strong gear for lawful minions (only difference
  should be that the weapon will no longer have a chance of generating at very
  high enchantment and keeping it; now it's just vanilla's +0 to +3 for swords
  and +3 to +6 for maces).
- Took vanilla's teledest implementation, which has better checks on the
  teledest coordinate.
- Took vanilla's (qt's) implementation of NO_PART for bodypart math.
- Took vanilla's teleport exclusion zones in the hellfill prefabs that contain
  some interior region that's blocked off somehow.
- Kept vanilla's changes to relative object probabilities, notably with
  spellbooks (which the DevTeam is treating as if every object class still has
  to add its probabilities up to 1000, which it doesn't).
- Took, for now, vanilla's enumeration of "all other" monster species in
  make_corpse (only compiled when NH_DEVEL_STATUS isn't "released"); but if this
  proves to be a headache-inducing source of merge conflicts, I may delete it.
- Took vanilla's implementation of blessed destroy armor scroll allowing you to
  choose the piece to destroy.
- Took saving grace without changes.
- Took vanilla's 3-stages-of-cracking system for glass armor. As of this commit,
  it applies only to armor, and glass weapons (and any other object classes)
  will still shatter completely the first time they take damage, but
  erodeproofing them still protects them. The game now uses vanilla's term
  "tempered" to denote some erodeproof glass object, except it still uses
  "indestructible" to refer to erodeproofed glass rings and wands which could
  also break from shock damage.
- Took vanilla's implementations of paranoid swim and paranoid trap. (This means
  if you do NOT have paranoid trap set, you will NOT be prompted to confirm
  before moving into a trap, and if you have it set but do not have paranoid
  confirm set, you will accept moving into it by pressing 'y').
- Took vanilla's implementation of force-fighting a web.
- Discarded xNetHack's "You find many hidden bugs on the floor" case for
  engraving with a wand of secret door detection, since it now always identifies
  itself.
- Adopted vanilla's code for handling searing damage from equipment on the left
  and right hands separately when a martial arts user gets a double attack,
  instead of just assuming searing damage would always be applied on every hit.
- Restored vanilla's behavior of not considering two objects mergable with
  different known, bknown or rknown - provided you are both a non-priest (for
  bknown) and are either blind or hallucinating, meaning most of the time, they
  are still mergable.
- Largely took the sacrifice gifting rebalance as-is; a few small notes:
  - Odds of a gift are 1/(6*gifts^2) instead of 1/(6*gifts*artifacts_existing).
  - Mirror Brand and the Apple of Discord need new +x and minimum sacrifice
    difficulty stats for the artifact rebalance made in vanilla. For now these
    are both zeroes; a follow-up commit will provide actual values. For Quest
    artifacts, the numbers are irrelevant, so I used the 0, 12 numbers for
    quest artifacts added in xNetHack, same as all the other quest artifacts.
- Took vanilla's implementation of shop annotations, deleting xNetHack function
  get_shtype() in the process.
- Took vanilla's code for suppressing the Quest leader summon message when the
  leader is dead (as opposed to xNetHack's slightly less accurate implementation
  of when you personally killed them).
- Took vanilla's code for item destruction, which was based on xNetHack code
  anyway and had only minor differences, mostly improvements.
- Took vanilla's implementation of looking up an object in inventory and
  discarded xNetHack's.

FEATURES WHERE THE XNETHACK IMPLEMENTATION WAS KEPT OR UPSTREAM CHANGES WERE
DISCARDED
- Barbed devils kept both their passive barb attack from xNetHack and their
  active sticky attack from vanilla (which replaced one of their claw attacks;
  they still only make 3 active attacks).
- Kept vrocks as orange, not green, though as of this commit their tile
  recoloration from vanilla to a greener demon has stayed.
- Discarded ice devil's slowing touch from vanilla. In xNetHack their cold sting
  already did this if you don't have cold resistance.
- Kept xNetHack secret door odds rather than vanilla's "none on first 2 levels,
  flat 1/8 beyond that". The xNetHack formula already has none on the first few
  levels and scales up gradually.
- Discarded various additions for the Rogue level such as traptype_roguelvl().
- Kept xNetHack's implementation of "concealed hiders don't venture out often";
  vanilla's happens before the m_move adjacent-finding code, which means
  monsters hiding in large grassy areas would move extremely slowly.
- Stripped the can_unlock and can_open arguments from postmov(), since they are
  used in mon_open_door, not here.
- Discarded NO_HIDING_UNDER_STATUES. The bug that led to its creation is already
  fixed upstream - monsters won't hide under statue trap statues because the
  space has a trap on it.
- Didn't take vanilla's "small bonus" for wielding a quarterstaff while
  spellcasting; this already confers a gear bonus in xNetHack.
- No updates to patchlevel since this is merged into the 9.0 savebreaking
  branch. EDITLEVEL is still 0.

FEATURES WHERE UPSTREAM AND XNETHACK IMPLEMENTATIONS WERE MERGED
- Vanilla added 4 guaranteed food rations to the Mon-strt level, whereas
  xNetHack added a chest with 5 random (not guaranteed vegetarian) comestibles.
  I moved the food rations into that chest and removed the 5 comestibles. It
  feels appropriate for the monks to only have bland food instead of an
  interesting variety. Also, fixed the location of the spinach tin to be next to
  the Grand Master, as it is in vanilla.
- Paupers keep race-based skill cap minimums, since these are natural affinities
  and not anything to do with background or training. (The hero doesn't actually
  start with any skill in them anyway.)
- Moved some code (regarding traps) from vanilla's implementation of
  can_hide_under_obj to xNetHack-native concealed_spot(), because vanilla
  assumes the only things that can hide monsters are objects, which is not true
  in xNetHack.
- Changed inventory weight format from "{xyz}" to vanilla's wizweight format of
  "(xyz aum)". If the extra 4 characters prove to make messages too long, this
  could be reverted, or have invweight turned into a compound option to select
  between styles. (Unlike in vanilla, non-wizards can still see object weights).
- Incorporated vanilla's code for protection from item destruction being
  percentage-based on worn gear (90% for dwarvish cloaks versus fire and cold),
  but maintained the principles from xNetHack commit e340c90 of keeping the
  protection symmetric for monsters and extrinsics being 100% protective.
- Took vanilla's unification of mulch logic in should_mulch_missile, but applied
  xNetHack-specific skill-based logic that favors the player. (Monsters' 2/3
  chance of breaking ammo is now 1/4, and is subject to the same
  enchantment-based and BUC-based saving throws to save or destroy it as the
  player gets.) Noticed a double implementation of "Flint and hard gems get an
  extra chance not to break because they don't easily break" and removed the
  extra one.
- Took vanilla's implementation of dipping in sinks, which allows washing hands
  and wetting objects in addition to identifying potions. It adds special
  effects for a few potions that weren't implemented in xNetHack, but I kept the
  xNetHack part where potions which unambiguously identify themselves by their
  effects on the sink get auto-identified rather than offering the player an
  opportunity to call them.
- Took vanilla's 30+d15 turns of invisibility from zapping self with a wand as
  opposed to xNetHack's 50+d50, but kept the xNetHack amount of d(spe*250) turns
  when breaking the wand.
- Discarded much of the vanilla code for a vampire reforming on a door and
  smashing it, specifically the part about triggering its trap which assumed the
  only door trap blows the door up. They will still smash doors, and they will
  still cause ones trapped with a fiery explosion to blow up, but they won't
  trigger other types of traps.
- Discarded xNetHack macro is_hard() in favor of vanilla's hard_helmet(), but
  moved the checks for other material helms that only exist in xNetHack (wood,
  bone, and stone) into that function.

FEATURES NOT ACTUALLY MERGED YET WHICH WILL GET A FOLLOW-UP COMMIT
- Artifact gift values for xNetHack-added artifacts as mentioned above.
- As of this commit, Dispater fiend adversity will usually completely shut down
  HP recovery, since the formula for HP recovery changed upstream.
- As of this commit, the xNetHack "garden" themed room coexists with paxed's
  "garden" themed room fill (which can appear in various room shapes). Other
  themed rooms still exist and haven't been checked for duplicates. They will
  probably be properly merged in a follow-up commit.
- Kept both vanilla's bone devil skeleton gating and xNetHack's bone devil
  skeleton summoning for now.
- As of this commit, both xNetHack fall damage from falling into open air and
  vanilla fall damage for falling down trapdoors (but which I believe also
  applies to falling into air) coexist.
- Erinyes are still guaranteed in some Gehennom special levels, which coexists
  with the new erinys revamp where they can be summoned to punish bad behavior.
  For now I kept their xNetHack statblock: G_NOGEN instead of G_SGROUP | 2,
  flying by default, green not red, always hostile.
- Temporarily left keeps_distance in mondata.h despite nhmall cleaning out the
  macros which took a struct monst * into mon.h. This will be fixed in a
  follow-up commit.

NEW IMPLEMENTATIONS IN THIS MERGE COMMIT
- Changed the code for vapors from the various potions of healing to call
  healup() instead of relying on janky switch case fallthru logic.
- Split part of ring_from_sink into a new function, find_sink_ring, which only
  returns the ring without making it come to the surface. This is so that
  pouring object detection down the sink can tell whether there's a ring there.
- Inserted a default case to some switch statements handling monsters that now
  get tripped up on -Werror=switch.
- Added some prototypes for html dumplog functions that never had them.

Author: copperwater

.gitignore

@@ -38,6 +38,9 @@ src/xnethack
 Debug/
 Release/
 binary/
+package/*
+vspackage/
+vsbinary/
 build/
 ipch/
 lib/*
@@ -94,3 +97,4 @@ bundle/*
 *.user
 util/*.lib
 util/*.exp
+submodules/CHKSUMS.tmp

Cross-compiling

@@ -20,6 +20,7 @@ Part B Contents:
     B4. Case sample: msdos
     B5. Case sample: amiga (started but incomplete)
     B6. Case sample: Web Assembly, libnh
+    B7. Case sample: mips
 
 --------------------------------------------------------------------------------
  Part A - Cross-compiling NetHack
@@ -360,41 +361,44 @@ Using the cross-compiler, build the following targets:
        cross-compile and link with these compiler switches:
          -DCROSSCOMPILE and -DCROSSCOMPILE_TARGET
 
-       core sources (2019): src/allmain.c, src/alloc.c, src/apply.c,
+       core sources (2024): src/allmain.c, src/alloc.c, src/apply.c,
                            src/artifact.c, src/attrib.c, src/ball.c,
-                           src/bones.c, src/botl.c, src/cmd.c, src/dbridge.c,
+                           src/bones.c, src/botl.c, src/calendar.c,
+                           src/coloratt.c, src/cmd.c, src/dbridge.c,
                            src/decl.c, src/detect.c, src/dig.c, src/display.c,
                            src/dlb.c, src/do.c, src/do_name.c, src/do_wear.c,
                            src/dog.c, src/dogmove.c, src/dokick.c,
                            src/dothrow.c, src/drawing.c, src/dungeon.c,
                            src/eat.c, src/end.c, src/engrave.c, src/exper.c,
-                           src/explode.c, src/files.c,
-                           src/fountain.c, src/hack.c, src/hacklib.c,
-                           src/insight.c, src/invent.c, src/isaac64.c,
-                           src/light.c, src/lock.c, src/mail.c,
-                           src/makemon.c, src/mcastu.c,
+                           src/explode.c, src/extralev.c, src/files.c,
+                           src/fountain.c, src/getpos.c, src/glyphs.c,
+                           src/hack.c, src/hacklib.c, src/insight.c,
+                           src/invent.c, src/isaac64.c, src/light.c,
+                           src/lock.c, src/mail.c, src/makemon.c, src/mcastu.c,
                            src/mdlib.c, src/mhitm.c, src/mhitu.c, src/minion.c,
                            src/mklev.c, src/mkmap.c, src/mkmaze.c, src/mkobj.c,
                            src/mkroom.c, src/mon.c, src/mondata.c,
                            src/monmove.c, src/monst.c, src/mplayer.c,
                            src/mthrowu.c, src/muse.c, src/music.c,
-                           src/nhlsel.c, src/nhlua.c, src/nhlobj.c,
-                           src/o_init.c, src/objects.c, src/objnam.c,
-                           src/options.c, src/pager.c, src/pickup.c,
-                           src/pline.c, src/polyself.c, src/potion.c,
-                           src/pray.c, src/priest.c, src/quest.c,
+                           src/nhlua.c, src/nhlsel.c, src/nhlobj.c,
+                           src/nhmd4.c, src/objects.c, src/o_init.c,
+                           src/objnam.c, src/options.c, src/pager.c,
+                           src/pickup.c, src/pline.c, src/polyself.c,
+                           src/potion.c, src/pray.c, src/priest.c, src/quest.c,
                            src/questpgr.c, src/read.c, src/rect.c,
-                           src/region.c, src/restore.c, src/rip.c, src/rnd.c,
-                           src/role.c, src/rumors.c, src/save.c, src/sfstruct.c,
-                           src/shk.c, src/shknam.c, src/sit.c, src/sounds.c,
-                           src/sp_lev.c, src/spell.c, src/steal.c, src/steed.c,
+                           src/region.c, src/report.c, src/restore.c,src/rip.c,
+                           src/rnd.c, src/role.c, src/rumors.c, src/save.c,
+                           src/selvar.c, src/sfstruct.c, src/shk.c,
+                           src/shknam.c, src/sit.c, src/sounds.c, src/sp_lev.c,
+                           src/spell.c, src/stairs.c, src/steal.c, src/steed.c,
                            src/symbols.c, src/sys.c, src/teleport.c,
                            src/timeout.c, src/topten.c, src/track.c,
-                           src/trap.c, src/u_init.c, src/uhitm.c, src/vault.c,
-                           src/version.c, src/vision.c,
-                           src/weapon.c, src/were.c, src/wield.c, src/windows.c,
-                           src/wizard.c, src/worm.c, src/worn.c, src/write.c,
-                           src/zap.c, sys/share/cppregex.cpp
+                           src/trap.c, src/u_init.c, src/uhitm.c,
+                           src/utf8map.c, src/vault.c, src/version.c,
+                           src/vision.c, src/weapon.c, src/were.c, src/wield.c,
+                           src/windows.c, src/wizard.c, src/wizcmds.c,
+                           src/worm.c, src/worn.c, src/write.c, src/zap.c,
+                           sys/share/cppregex.cpp
 
        tty sources:        win/tty/getline.c, win/tty/termcap.c,
                            win/tty/topl.c, win/tty/wintty.c
@@ -409,7 +413,7 @@ Using the cross-compiler, build the following targets:
 
     b) Lua (mandatory in 3.7)
 
-          lib/lua-5.4.4/src
+          lib/lua-5.4.6/src
 
                    from sources: lua.c, lapi.c, lauxlib.c, lbaselib.c, lcode.c,
                                  lcorolib.c, lctype.c, ldblib.c, ldebug.c,
@@ -468,18 +472,18 @@ Cross-compiler pre-built binary downloads:
        or pdcursesmod from:
            https://github.com/Bill-Gray/PDCursesMod.git
 
-    - A shell script to download that djgpp cross-compiler and associated
+    - A bash script to download that djgpp cross-compiler and associated
       pieces for either linux or macOS is available:
 
-           sh sys/msdos/fetch-cross-compiler.sh
+           bash sys/msdos/fetch-cross-compiler.sh
 
     That script won't install anything, it just does file fetches and stores
     them in subfolders of lib. The linux.370 and macOS.370 hints files are
     configured to find the cross-compiler there if you add
         CROSS_TO_MSDOS=1
     on your make command line.
 
-    Note: Both the fetch-cross-compiler.sh script and and the msdos
+    Note: Both the fetch-cross-compiler.sh bash script and the msdos
     cross-compile and package procedures require unzip and zip to be available
     on your host build system.
 
@@ -554,7 +558,7 @@ Cross-compiler url:      https://github.com/bebbo/amiga-gcc
             make update
 
            [Note that you may have to take ownership of the files in the bebbo
-            repo via chown before succesfully carrying out the next steps]
+            repo via chown before successfully carrying out the next steps]
 
             make clean
             make clean-prefix
@@ -692,5 +696,38 @@ Cross-compiler url: https://emscripten.org/docs/getting_started/downloads.html
     and shouldn't interfere with the non-cross-compile builds using
     hints/linux.370 or hints/macOS.370.
 
+
+  +--------------------------------+
+  | B7. Case sample: mips          |
+  +--------------------------------+
+
+Cross-compiler used: gcc-mipsel-linux-gnu, g++-mipsel-linux-gnu
+Cross-compiler url:
+
+    Here's a brief guide to obtaining the cross-compiler sources on an
+    Ubuntu system and building NetHack with it.
+
+    For Ubuntu, the build prerequisite packages for building the compiler can
+    be easily obtained:
+        sudo apt install gcc-mipsel-linux-gnu
+        sudo apt install g++-mipsel-linux-gnu
+
+    On your linux host, prepare to cross-compile NetHack as follows:
+        cd sys/unix ; sh setup.sh hints/linux.370 ; cd ../..
+        make fetch-lua
+
+    Then, cross-compile to targets/mips as follows:
+        make CROSS_TO_MIPS=1 fetch-ncurses
+        make CROSS_TO_MIPS=1 package
+
+    Do not add any additional windowport interfaces to your build
+    (such as WANT_WIN_TTY=1 WANT_WIN_CURSES=1 WANT_WIN_X11=1 or
+    WANT_WIN_QT=1) as those aren't applicable to the mips cross-compile.
+
+    The cross-compiler hints additions are enclosed inside ifdef sections
+    and shouldn't interfere with the non-cross-compile builds using
+    hints/linux.370 or hints/macOS.370.
+
+
 ---
 

DEVEL/Developer.txt

@@ -58,18 +58,36 @@ NOTE: These instructions assume you are on the default branch; this _is_
 NOTE: The following instructions require perl.  If you do not have perl on
       your system, please install it before proceeding.
 
+NOTE: More information on nhgitset.pl is available before installation via:
+           perldoc DEVEL/nhgitset.pl
+      After installation, the same information is available with:
+           git nhhelp nhgitset
+
 A. If you have never set up git on this machine before:
    (This assumes you will only be using git for NetHack.  If you are going to
    use it for other projects as well, think before you type.)
 	Tell git what name (or nickname) and email address to use for you:
 		git config --global user.name "MY NAME"
 		git config --global user.email USER@EXAMPLE.COM
    You probably want to set up a credential cache.
-	macOS (10 - 12):
-		git config --global credential.helper osxkeychain
-	Windows:
-		git config --global credential.helper store
-XXX linux
+	macOS (10 or greater):
+	    git config --global credential.helper osxkeychain
+	Linux:
+	    (This will vary by distribution.)
+	    cd /usr/share/doc/git/contrib/credentail/libsecret
+	    sudo apt-get install libglib-2.0-dev libsecret-1-dev
+	    sudo make
+	    git config --global credential.helper `pwd`/git-credential-libsecret
+		OR
+	    sudo yum install git-credential-libsecret
+	    git config --global credential.helper /usr/libexec/git-core/git-credential-libsecret
+	Windows: (The following three assume that Git for Windows is already installed on
+	          the underlying Windows system https://git-scm.com/download/win):
+	    git config --global credential.helper store
+          MSYS2 UCRT64 bash shell:
+            git config --global credential.helper "/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe"
+	  Windows Subsystem for Linux 2 (WSL2) bash shell:
+            git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe"
 B. Specify the prefix for variable substitution:
    (This assumes you are not a member of DevTeam or any variant's development
    team.  If you are, this may be wrong.  Look for more specific documentation.
@@ -79,10 +97,11 @@ B. Specify the prefix for variable substitution:
 	tree you cloned from git.  I use ~/nethack/GITADDDIR; for that base,
 	create the needed directories and edit the file:
 		~/nethack/GITADDDIR/DOTGIT/PRE
-	Put this in it (if your OS is not Unix-like you may need to change
-	the first line):
+	Put this in it, adapting it to your variant (if your OS is not Unix-like
+	you may need to change the first line):
 		#!/bin/sh
 		git config nethack.substprefix MINE
+		git config nethack.projectname MineHack
 	Now make it executable:
 		chmod +x ~/nethack/GITADDDIR/DOTGIT/PRE
 C. Configure the repository:
@@ -156,8 +175,8 @@ A. Introduction
    The PREFIX is the value in the git config variable nethack.substprefix.
    VARNAME is one of:
 	Date
-	Branch (experimental)
-	Revision (experimental)
+	Branch
+	Revision
    other names will give a warning.
 
 B. Enabling variable expansion

DEVEL/VERSION

@@ -0,0 +1,4 @@
+5
+Please see "git log DEVEL" for previous changes.
+Make documentation of nhgitset.pl easier to find and
+find out about.

DEVEL/code_features.txt

@@ -101,6 +101,23 @@ engine are incompatible.
 Additional regular expression implementations can be written. The full
 interface documentation is in sys/share/posixregex.c
 
+===========================================================
+HEADER FILE NOTES
+
+hack.h defines values that are available to all NetHack source files,
+contains enums for use in all NetHack source files, and contains a
+number of struct definitions for use in all NetHack source files.
+hack.h does not contain variable declarations or variable definitions.
+
+decl.h and decl.c are related: decl.h contains the extern declarations
+for variables that are defined in decl.c. These variables are global
+and available to all NetHack source files.
+decl.c variable definitions are generally laid out in much the same
+order as their corresponding declarations in decl.h.
+
+A new header file cstd.h was added to coincide with 3.7's switch to
+C99. It contains calls to some C99 standard header files.
+
 =================== NEXT FEATURE ==========================
 
 

DEVEL/code_style.txt

@@ -1,4 +1,4 @@
-# NetHack 3.7  code_style.txt       $NHDT-Date: 1596498264 2020/08/03 23:44:24 $  $NHDT-Branch: NetHack-3.7 $:$NHDT-Revision: 1.5 $
+# NetHack 3.7  code_style.txt       $NHDT-Date: 1694890786 2023/09/16 18:59:46 $  $NHDT-Branch: NetHack-3.7 $:$NHDT-Revision: 1.8 $
 # Copyright (c) 2015 by Derek S. Ray
 # NetHack may be freely redistributed.  See license for details.
 
@@ -45,7 +45,7 @@ possible:
 Single blank lines should be used wherever convenient to improve readability.
 
 Functions and Control Statements
--------------------------------
+--------------------------------
 
 For a function definition, the return type, declarator, and opening brace
 should each appear on a line of their own. Arguments are defined in the following
@@ -170,6 +170,19 @@ Variable names to avoid
                  processors with segmented architectures may treat
                  those as keywords. It is safest to just avoid them.
 
+    NEARDATA     Some data is marked with this define; the Amiga port uses
+                 it to mark data items to be used with a short addressing mode.
+                 You don't need to use this.
+
+static vs staticfn
+------------------
+
+The staticfn macro evaluates to either "static" or to nothing (see config.h).
+If possible, functions in src/*.c that would otherwise be marked static should
+be marked staticfn so platforms that do not name static functions in their
+stack traces can be forced to do so; this means function names cannot be
+reused.  Never use staticfn with data.
+
 Spaces in Expressions
 ---------------------
 
@@ -183,6 +196,63 @@ immediately inside a pair of parentheses:
         /* body */
     }
 
+Casts and sizeof
+----------------
+
+Casts should separate the cast operator and its expression with a space:
+    '(char *) str'
+'sizeof (type)' requires the parentheses.  'sizeof expression' does not;
+using them is not wrong but omitting them avoids some visual clutter.
+Using them without the separating space gives the false impression of a
+function call or macro-with-argument(s) expansion; 'sizeof' is an operator
+and the parentheses required for '(type)' are to treat it like a cast.
+
+Comments
+--------
+
+Some block comments are undecorated, just split into reasonable width lines:
+    /* this is
+       a comment */
+They usually don't include sentence punctuation.
+
+Others are more elaborate:
+    /*
+     * This is
+     * another comment.
+     */
+This style is usually used with sentence punctuation, particularly if they
+contain more than one sentence.
+
+End-of-line comments which need to span lines
+    somecode(); /* this comment
+                 * is ok */
+should start every continuation line with an asterisk, otherwise clang-format
+would convert them into a block comment
+    othercode(); /* this comment
+                    should be avoided */
+because it would be converted into
+    othercode();
+    /* this comment
+       should be avoided */
+if another bulk reformatting ever gets performed.  Similarly, multiple
+comments intended to read as one
+    morecode(); /* start of comment */
+                /* more of comment  */
+                /* end of comment   */
+are deprecated because they will end up losing the indentation of the
+followup lines if reformatted.
+
+Many files end with
+    /*filename*/
+usually preceded by a blank line.  This was intended as a workaround for a
+comment--somewhere, possibly in Amiga or Atari code--that stated that some
+compiler or other didn't always process the last line of the file.  If that
+last line is a comment, nothing is lost.  The real issue almost certainly
+was source file(s) that didn't end in newline.  These days we try to force
+the final newline for every file, prior to release if not always maintained
+day-to-day.  The name at the end can still be worthwhile when editing or
+browsing multiple files.
+
 Vim Configuration
 =================
 
@@ -202,7 +272,7 @@ ensure that indentation is done correctly:
 Visual Studio Configuration
 ===========================
 
-In Visual Studio under Tools->Options->Text Editor->C/C++, you can set the 
+In Visual Studio under Tools->Options->Text Editor->C/C++, you can set the
 following options to obtain desired behavior:
 
 [Tabs]
@@ -213,8 +283,8 @@ Insert Spaces
 
 There are a number of other options under [Formatting] that should be
 checked (Indentation, New Lines, Spacing, and Wrapping), but there are so
-many entries that reproducing them here is impractical. Fortunately, the 
-options are in plain English, so walking through them with a copy of 
+many entries that reproducing them here is impractical. Fortunately, the
+options are in plain English, so walking through them with a copy of
 this Guide handy and making changes as required will suffice.
 
 Emacs Configuration