The gm script, aka gmX (All GMs)

When you set up your dotfiles for Template use you were advised to (a) copy bin/gm from the published Template tree into your homedir and (b) make a gmfoo alias for each game Foo you're working on with --game set to Foo's $GAME. Since we don't know what "gmfoo" name you used, all Template docs will say "gmX" to mean "whatever your alias is" (you're not likely to run the "raw" gm script unaliased).

Using gmX

All GMs should read this; it's what you actually do to run scripts.

Details on gmX

The Czar probably wants to read this; other GMs may want to. It explains more of what gmX is doing and its purpose. (Definitely read this before writing/editing scripts running under gmX yourself.)

You use gmX to run your game's bin/ perl scripts:

gmX [gm options] [scriptname [script arguments]]

Your gmX alias should include a --game setting. If this directory does not match your current $GAME directory, gmX reports this and exits. This means you can't be in "working on game Foo" mode and accidentally call scripts from game Bar, with Bar configurations, to screw up one or both games.

If scriptname is not found in bin/, it's treated as a possible abbreviation. (At least three characters of the name must be given.) If a unique match is found, it is used; otherwise, gmX displays the possible matches and exits. If you omit scriptname it displays all possibilities and exits.

(Possibilities are always limited to readable, executable, non-empty plaintext files, so that it doesn't try to use a configuration file or random binary as Perl.)

--help

Print usage message and exit.

--version

Print version information and exit.

--game=gamepath

Specify directory path that $GAME must match; mandatory unless using --help or --version, which exit without using another script. (The actual directories must match; the strings don't have to.)

--tmp=tmpdir

Provide wrapped script access to (and create if necessary) temporary directory tmpdir instead of the default. (See Details.)

--unsafe

Disable the safety features, lifting restrictions from the wrapped script. See Details; do not use this option without knowing what it does.

The primary purpose of gmX is to be a single point of entry for the bin/ scripts. You no longer have to either provide the full path from wherever you happen to be to bin/ or add $GAME/bin to your path (which is a pain, dangerous, and almost certain to screw you up if you're working on multiple games).

The secondary purpose of gmX is to provide GMs some safeties. It restricts the wrapped scripts from doing dangerous things like screwing around outside the game dir (like in your homedir) or executing arbitrary shell commands. The main goal here is to protect you from stupid mistakes made by your Czar or other GMs writing/editing scripts or for that matter by Template developers; a stupid mistake in writing or using a script meant to clean out unwanted files from game, for instance, won't be allowed to "clean" out files from your home directory. ("Where did my thesis go?!?") It also can't accidentally screw with your other game lockers. A merely side goal of the safties is to protect you against malicious code, since if another GM gets pissed at you they could edit a script you run to send them copies of all your mail, erase all your files, email bomb threats to the CPs from your account, post desperate solicitations from your account to every alt.sex newsgroup, and otherwise be annoying. The gmX wrapper probably prevents the really nasty possibilities, though latex's own file read-write capabilities (which at least cannot write dotfiles) allow some amount of damage from a malicious .tex file when you latex it yourself, so it's not perfect safety. Again, that's only the side goal of the safety restrictions.

(This is why we suggest copying bin/gm to your homedir from the public release tree, to be sure you have an exact copy. If you already have one, you could run diff to see if the public release is any newer, and/or look at the --version information. You should be able to use any version of gm no older than your game's Template release; an older version of gm might be a problem, but a newer one should never be.)

If there's a script you really want to run that tries something gmX won't allow, you can run gmX --unsafe, which disables the restrictions. This is, obviously, not at all recommended. You could also just write the script to run on its own, not under gmX, though then you won't get things like the automatic .structure translation we're about to mention.

If your game is using the optional .structure file, gmX reads and implements it. Functions are provided to wrapped scripts to look at translations, though mostly they'll just call gmX functions that deal transparently.

It also provides a directory for working space for the wrapped script, so that temporary things can be put outside $GAME, especially large things. (This is the only area outside $GAME that can be freely affected. Don't set it to your homedir.) Writing $GAME as (stuff)/foo/bar/, the temp dir defaults to /tmp/USERNAME-foo-bar/ (which usually looks like /tmp/USERNAME-games-Blah/ or /tmp/USERNAME-Blah-Template/ depending on whether your Template stuff is in a "Template" subdir of the game). The --tmp option overrides the default. In some cases you may want to look at the files produced in the temp dir, e.g. with the packets script output, though that script also provides an --ingame option to work in $GAME directly. Note that on Athena workstations /tmp is cleaned between logins.

For information on what gmX does from the point of view of writing/editing a wrapped script, see the pod (i.e. do perldoc ~/gm) and see the bin/ scripts code for examples. For the nitty-gritty details see the source code and its comments.