254 lines
10 KiB
Plaintext
254 lines
10 KiB
Plaintext
___ _
|
|
| \ _____ _____| |___ _ __ ___ _ _
|
|
| |) / -_) V / -_) / _ \ '_ \/ -_) '_|
|
|
|___/\___|\_/\___|_\___/ .__/\___|_|
|
|
|_|
|
|
|
|
# NetHack 3.7 Developer.txt $NHDT-Date: 1596498265 2020/08/03 23:44:25 $ $NHDT-Branch: NetHack-3.7 $:$NHDT-Revision: 1.19 $
|
|
# Copyright (c) 2015 by Kenneth Lorber, Kensington, Maryland
|
|
# NetHack may be freely redistributed. See license for details.
|
|
|
|
Welcome to the NetHack Infrastructure Developer's Guide.
|
|
|
|
This is the info you need if you are developing code for NetHack.
|
|
(This information is from DevTeam. If you are working with a variant please
|
|
check for additional documentation for that variant.)
|
|
|
|
For information on building NetHack, see README in the top level directory.
|
|
For information on playing NetHack, see the Guidebook in the doc directory.
|
|
|
|
DANGER! WORK IN PROGRESS! Known issues marked XXX.
|
|
|
|
CONTENTS
|
|
1. email
|
|
2. git repositories
|
|
3. bug reporting
|
|
4. git configuration
|
|
5. variable expansion
|
|
6. reserved names
|
|
7. nhadd/nhcommit
|
|
8. hooks
|
|
------------------------------------------------------------------------------
|
|
1. email
|
|
Email to devteam@nethack.org will usually get a response, but it may take a
|
|
while. Please do not send save files, binary screen grabs, or other large
|
|
things.
|
|
------------------------------------------------------------------------------
|
|
2. git repositories
|
|
The public NetHack git repository is available (read-only) at:
|
|
https://github.com/NetHack/NetHack
|
|
or
|
|
https://sourceforge.net/p/nethack/NetHack/
|
|
|
|
Branches:
|
|
NetHack-3.6.0 The 3.6.0 release code and subsequent fixes and additions.
|
|
------------------------------------------------------------------------------
|
|
3. bug reporting
|
|
Please use the form at http://www.nethack.org/common/contact.html (or send
|
|
us an email if that's more appropriate).
|
|
------------------------------------------------------------------------------
|
|
4. git configuration
|
|
|
|
NOTE: These instructions assume you are on the default branch; this _is_
|
|
where you want to be for setting things up. This may or may not be
|
|
the branch you want to use for your changes; see the appropriate
|
|
project private documentation for more information (if you are working
|
|
alone we suggest using branch names starting with "LOCAL-").
|
|
|
|
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 or greater):
|
|
git config --global credential.helper osxkeychain
|
|
Linux:
|
|
(This will vary by distribution.)
|
|
cd /usr/share/doc/git/contrib/credential/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.
|
|
For example, this file uses "MINE" for the substitution prefix - this will
|
|
almost always be wrong if you are working with someone else.)
|
|
Decide where you want to put this info; it should NOT be inside the
|
|
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, 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:
|
|
- cd to the top level of the repository
|
|
- tell the repository about the directory you created above:
|
|
git config nethack.gitadddir FULL_PATH_TO_GITADDDIR
|
|
so for the example above:
|
|
git config nethack.gitadddir ~/nethack/GITADDDIR
|
|
- do the automated setup:
|
|
perl DEVEL/nhgitset.pl
|
|
If it complains, fix what it complains about. nhgitset.pl accepts
|
|
the following options:
|
|
-v verbose
|
|
-n dry run
|
|
You can re-run nhgitset.pl as often as needed; occasionally we will
|
|
update it (or something it installs) and you will need to run it again
|
|
so the changes take effect.
|
|
D. aliases
|
|
Two aliases are installed by nhgitset.pl:
|
|
nhadd
|
|
nhcommit
|
|
These two commands take the same options as the normal git add and commit
|
|
commands but perform RCS/CVS-style variable substitution.
|
|
|
|
Note that nothing terrible will happen if you do not use the nh* versions
|
|
of the commands.
|
|
|
|
Supported substitutions:
|
|
MINE-Date the commit time and date
|
|
Experimental substitutions:
|
|
MINE-Revision CVS style revision number
|
|
MINE-Branch the current git branch
|
|
|
|
For direct access to the substitution mechanism, use:
|
|
nhsub
|
|
|
|
See the section "nhadd/nhcommit" for details on those aliases.
|
|
Run "perldoc DEVEL/hooksdir/nhsub" for details on nhsub.
|
|
|
|
That's it. If you need to do something more when setting up your repository,
|
|
keep reading. Otherwise, you are done with this section.
|
|
|
|
1) to run your own hooks in addition to ours:
|
|
name your hook
|
|
WHEN-HOOKNAME
|
|
where WHEN is
|
|
PRE (run your code before the NetHack hook)
|
|
POST (run your code after the NetHack hook)
|
|
and HOOKNAME is the normal git name of the hook.
|
|
Make sure the hooks are executable (chmod +x ...).
|
|
Be sure to test carefully since the composition of two bits of code may or
|
|
may not do what you want.
|
|
2) to install other bits on setup:
|
|
Put additional files in the GITADDDIR tree. Use "DOTGIT" instead of
|
|
".git". If a file called PRE, POST, or INSTEAD exists in a
|
|
subdirectory of GITADDDIR, it is run before the copy, after the copy,
|
|
or instead of the copy. No copy operation is attempted in the DOTGIT
|
|
directory; use a script and standard git commands to change the
|
|
contents as needed.
|
|
3) NB: In all namespaces, anything that matches m/^nh/i or m/^nethack/i is
|
|
reserved.
|
|
------------------------------------------------------------------------------
|
|
5. variable expansion
|
|
A. Introduction
|
|
We have implemented an RCS/CVS/SVN style variable expansion mechanism.
|
|
References of either of the formats:
|
|
$PREFIX-VARNAME$
|
|
$PREFIX-VARNAME: VALUE $
|
|
will be handled (if enabled).
|
|
|
|
The PREFIX is the value in the git config variable nethack.substprefix.
|
|
VARNAME is one of:
|
|
Date
|
|
Branch
|
|
Revision
|
|
other names will give a warning.
|
|
|
|
B. Enabling variable expansion
|
|
Variable expansion is controlled by the .gitattributes file.
|
|
|
|
To enable variable expansion:
|
|
pattern NHSUBST
|
|
To disable variable expansion:
|
|
pattern -NHSUBST
|
|
|
|
More information: "git help gitattributes"
|
|
|
|
C. Oddities
|
|
To trigger variable expansion, you _must_ use "git nhadd" or "git nhcommit"
|
|
instead of "git add" or "git commit." Nothing terrible will happen if you
|
|
use the wrong one, but the values will not be updated.
|
|
|
|
Variable expansion modifies the files in the work tree - your editor or
|
|
IDE may or may not be happy with this.
|
|
|
|
D. Using your own hooks
|
|
You can use your own hooks - put them in .git/hooks as usual BUT name them
|
|
as follows:
|
|
WHEN-HOOKNAME
|
|
where WHEN is:
|
|
PRE (execute the code before the NetHack hook)
|
|
POST (execute the code after the NetHack hook)
|
|
and HOOKNAME is the normal git name for the hook.
|
|
|
|
Test carefully - interactions between hooks can be nasty.
|
|
------------------------------------------------------------------------------
|
|
6. reserved names
|
|
Anything that matches m/^nh/i or m/^nethack/i is reserved in all
|
|
namespaces (environment, file names, git config, etc).
|
|
------------------------------------------------------------------------------
|
|
7. nhadd/nhcommit
|
|
nhadd is essentially "git nhsub $*; git add $*"
|
|
nhcommit is essentially "git nhsub $*; git commit $*"
|
|
|
|
As "git add" and "git commit" have complex arguments, nhsub attempts to
|
|
do the right thing - or at least something reasonable - for most arguments.
|
|
If nhadd/nhcommit don't do what you need, run "git nhsub" on its own then
|
|
add/commit.
|
|
|
|
So when do I need to use what?
|
|
The object is to get nhsub run right before git takes a snapshot of each
|
|
file. So for example:
|
|
- use "git nhcommit <filespec>" instead of "git commit <filespec>"
|
|
- use "git nhadd <filespec>" instead of "git add <filespec>"
|
|
- use either "git commit" or "git nhcommit" (because the snapshot was
|
|
already taken)
|
|
- if you use "git nhsub <filespec>" then you can "git add <filespec>" or
|
|
"git commit <filespec>"
|
|
|
|
For more complex situations, "git nhsub" takes -v and -n flags - see
|
|
"perldoc DEVEL/hooksdir/nhsub".
|
|
|
|
------------------------------------------------------------------------------
|
|
8. hooks
|
|
|
|
nhgitset.pl also installs hooks into .git/hooks. These hooks provide
|
|
a framework which allows local hook code to co-exist with hook code we
|
|
supply - see DEVEL/hooksdir/NHgithook.pm for details.
|
|
|
|
We currently use the following hooks:
|
|
post-checkout
|
|
post-commit
|
|
post-merge
|
|
These are used to generate dat/gitinfo.txt which provides the data that
|
|
ends up available through the game command #version and the command line
|
|
option --version.
|
|
|
|
------------------------------------------------------------------------------
|
|
|