DEVEL/Developer.txt

   1   ___              _
   2  |   \ _____ _____| |___ _ __  ___ _ _
   3  | |) / -_) V / -_) / _ \ '_ \/ -_) '_|
   4  |___/\___|\_/\___|_\___/ .__/\___|_|
   5                         |_|
   6
   7 # NetHack 3.6  Developer.txt       $NHDT-Date: 1524689668 2018/04/25 20:54:28 $  $NHDT-Branch: NetHack-3.6.0 $:$NHDT-Revision: 1.13 $
   8 # Copyright (c) 2015 by Kenneth Lorber, Kensington, Maryland
   9 # NetHack may be freely redistributed.  See license for details.
  10
  11 Welcome to the NetHack Infrastructure Developer's Guide.
  12
  13 This is the info you need if you are developing code for NetHack.
  14 (This information is from DevTeam.  If you are working with a variant please
  15 check for additional documentation for that variant.)
  16
  17 For information on building NetHack, see README in the top level directory.
  18 For information on playing NetHack, see the Guidebook in the doc directory.
  19
  20 DANGER!  WORK IN PROGRESS!  Known issues marked XXX.
  21
  22 CONTENTS
  23 1. email
  24 2. git repositories
  25 3. bug reporting
  26 4. git configuration
  27 5. variable expansion
  28 6. reserved names
  29 7. nhadd/nhcommit
  30 8. hooks
  31 ------------------------------------------------------------------------------
  32 1. email
  33 Email to devteam@nethack.org will usually get a response, but it may take a
  34 while.  Please do not send save files, binary screen grabs, or other large
  35 things.
  36 ------------------------------------------------------------------------------
  37 2. git repositories
  38 A public repository of the latest NetHack code that we've made
  39 available can be obtained via git from either of two locations:
  40     https://github.com/NetHack/NetHack
  41      or
  42     https://sourceforge.net/p/nethack/NetHack/
  43
  44 Branches:
  45 NetHack-3.6.0   The 3.6.0 release code and subsequent fixes and additions.
  46 ------------------------------------------------------------------------------
  47 3. bug reporting
  48 Please use the form at http://www.nethack.org/common/contact.html (or send
  49 us an email if that's more appropriate).
  50 ------------------------------------------------------------------------------
  51 4. git configuration
  52
  53 NOTE: These instructions assume you are on the default branch; this _is_
  54       where you want to be for setting things up.  This may or may not be
  55       the branch you want to use for your changes; see the appropriate
  56       project private documentation for more information (if you are working
  57       alone we suggest using branch names starting with "LOCAL-").
  58
  59 NOTE: The following instructions require perl.  If you do not have perl on
  60       your system, please install it before proceeding.
  61
  62 A. If you have never set up git on this machine before:
  63    (This assumes you will only be using git for NetHack.  If you are going to
  64    use it for other projects as well, think before you type.)
  65         Tell git what name (or nickname) and email address to use for you:
  66                 git config --global user.name "MY NAME"
  67                 git config --global user.email USER@EXAMPLE.COM
  68    You probably want to set up a credential cache.
  69         Mac OS X:
  70                 git config --global credential.helper osxkeychain
  71         Windows:
  72                 git config --global credential.helper store
  73 XXX linux
  74 B. Specify the prefix for variable substitution:
  75    (This assumes you are not a member of DevTeam or any variant's development
  76    team.  If you are, this may be wrong.  Look for more specific documentation.
  77    For example, this file uses "MINE" for the substitution prefix - this will
  78    almost always be wrong if you are working with someone else.)
  79         Decide where you want to put this info; it should NOT be inside the
  80         tree you cloned from git.  I use ~/nethack/GITADDDIR; for that base,
  81         create the needed directories and edit the file:
  82                 ~/nethack/GITADDDIR/DOTGIT/PRE
  83         Put this in it (if your OS is not Unix-like you may need to change
  84         the first line):
  85                 #!/bin/sh
  86                 git config nethack.substprefix MINE
  87         Now make it executable:
  88                 chmod +x ~/nethack/GITADDDIR/DOTGIT/PRE
  89 C. Configure the repository:
  90         - cd to the top level of the repository
  91         - tell the repository about the directory you created above:
  92                 git config nethack.gitadddir FULL_PATH_TO_GITADDDIR
  93            so for the example above:
  94                 git config nethack.gitadddir ~/nethack/GITADDDIR
  95         - do the automated setup:
  96                 perl DEVEL/nhgitset.pl
  97           If it complains, fix what it complains about.  nhgitset.pl accepts
  98           the following options:
  99                 -v verbose
 100                 -n dry run
 101    You can re-run nhgitset.pl as often as needed; occasionally we will
 102    update it (or something it installs) and you will need to run it again
 103    so the changes take effect.
 104 D. aliases
 105    Two aliases are installed by nhgitset.pl:
 106         nhadd
 107         nhcommit
 108    These two commands take the same options as the normal git add and commit
 109    commands but perform RCS/CVS-style variable substitution.
 110
 111    Note that nothing terrible will happen if you do not use the nh* versions
 112    of the commands.
 113
 114    Supported substitutions:
 115         MINE-Date       the commit time and date
 116    Experimental substitutions:
 117         MINE-Revision   CVS style revision number
 118         MINE-Branch     the current git branch
 119
 120    For direct access to the substitution mechanism, use:
 121         nhsub
 122
 123    See the section "nhadd/nhcommit" for details on those aliases.
 124    Run "perldoc DEVEL/hooksdir/nhsub" for details on nhsub.
 125
 126 That's it.  If you need to do something more when setting up your repository,
 127 keep reading.  Otherwise, you are done with this section.
 128
 129 1) to run your own hooks in addition to ours:
 130         name your hook
 131                 WHEN-HOOKNAME
 132         where WHEN is
 133                 PRE     (run your code before the NetHack hook)
 134                 POST    (run your code after the NetHack hook)
 135         and HOOKNAME is the normal git name of the hook.
 136    Make sure the hooks are executable (chmod +x ...).
 137    Be sure to test carefully since the composition of two bits of code may or
 138    may not do what you want.
 139 2) to install other bits on setup:
 140         Put additional files in the GITADDDIR tree.  Use "DOTGIT" instead of
 141         ".git".  If a file called PRE, POST, or INSTEAD exists in a
 142         subdirectory of GITADDDIR, it is run before the copy, after the copy,
 143         or instead of the copy.  No copy operation is attempted in the DOTGIT
 144         directory; use a script and standard git commands to change the
 145         contents as needed.
 146 3) NB: In all namespaces, anything that matches m/^nh/i or m/^nethack/i is
 147    reserved.
 148 ------------------------------------------------------------------------------
 149 5. variable expansion
 150 A. Introduction
 151    We have implemented an RCS/CVS/SVN style variable expansion mechanism.
 152    References of either of the formats:
 153         $PREFIX-VARNAME$
 154         $PREFIX-VARNAME: VALUE $
 155    will be handled (if enabled).
 156
 157    The PREFIX is the value in the git config variable nethack.substprefix.
 158    VARNAME is one of:
 159         Date
 160         Branch (experimental)
 161         Revision (experimental)
 162    other names will give a warning.
 163
 164 B. Enabling variable expansion
 165    Variable expansion is controlled by the .gitattributes file.
 166
 167    To enable variable expansion:
 168         pattern NHSUBST
 169    To disable variable expansion:
 170         pattern -NHSUBST
 171
 172    More information: "git help gitattributes"
 173
 174 C. Oddities
 175    To trigger variable expansion, you _must_ use "git nhadd" or "git nhcommit"
 176    instead of "git add" or "git commit."  Nothing terrible will happen if you
 177    use the wrong one, but the values will not be updated.
 178
 179    Variable expansion modifies the files in the work tree - your editor or
 180    IDE may or may not be happy with this.
 181
 182 D. Using your own hooks
 183    You can use your own hooks - put them in .git/hooks as usual BUT name them
 184    as follows:
 185         WHEN-HOOKNAME
 186    where WHEN is:
 187         PRE     (execute the code before the NetHack hook)
 188         POST    (execute the code after the NetHack hook)
 189    and HOOKNAME is the normal git name for the hook.
 190
 191    Test carefully - interactions between hooks can be nasty.
 192 ------------------------------------------------------------------------------
 193 6. reserved names
 194    Anything that matches m/^nh/i or m/^nethack/i is reserved in all
 195    namespaces (environment, file names, git config, etc).
 196 ------------------------------------------------------------------------------
 197 7. nhadd/nhcommit
 198    nhadd is essentially "git nhsub $*; git add $*"
 199    nhcommit is essentially "git nhsub $*; git commit $*"
 200
 201    As "git add" and "git commit" have complex arguments, nhsub attempts to
 202    do the right thing - or at least something reasonable - for most arguments.
 203    If nhadd/nhcommit don't do what you need, run "git nhsub" on its own then
 204    add/commit.
 205
 206    So when do I need to use what?
 207    The object is to get nhsub run right before git takes a snapshot of each
 208    file.  So for example:
 209    - use "git nhcommit <filespec>" instead of "git commit <filespec>"
 210    - use "git nhadd <filespec>" instead of "git add <filespec>"
 211    - use either "git commit" or "git nhcommit" (because the snapshot was
 212      already taken)
 213    - if you use "git nhsub <filespec>" then you can "git add <filespec>" or
 214      "git commit <filespec>"
 215
 216    For more complex situations, "git nhsub" takes -v and -n flags - see
 217    "perldoc DEVEL/hooksdir/nhsub".
 218
 219 ------------------------------------------------------------------------------
 220 8. hooks
 221
 222    nhgitset.pl also installs hooks into .git/hooks.  These hooks provide
 223    a framework which allows local hook code to co-exist with hook code we
 224    supply - see DEVEL/hooksdir/NHgithook.pm for details.
 225
 226    We currently use the following hooks:
 227     post-checkout
 228     post-commit
 229     post-merge
 230    These are used to generate dat/gitinfo.txt which provides the data that
 231    ends up available through the game command #version and the command line
 232    option --version.
 233
 234 ------------------------------------------------------------------------------
 235