DEVEL/Developer.txt

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