============================================================================ Upgrading to PennMUSH 1.8.x ============================================================================ This file explains how to upgrade to a new version of PennMUSH. There are three basic upgrade situations: A. You're running a stock ("vanilla") PennMUSH server of some version and you want to upgrade to a later version B. You've hacked your server source code a little bit here and there (adding a flag, for example). Hacks to the *local.c files don't count as hacks, as they're easy to handle. C. You've hacked your server source code a lot. There is also a list of upgrade "GOTCHAS" at the end of this file. Please read them. The PennMUSH developers actually only support situation A, but we'll give some useful tips for B and C here, too. DISCLAIMER: It is very wise to always back up your current working MUSH directories before you try an upgrade. You were warned. ============================================================================ A. Vanilla upgrade You have basically two choices here: upgrade with patch files, or build a whole new distribution. A.1. Upgrading with patch files This is the easiest way to upgrade your source code if you're keeping up with patches as they come out, or if you're upgrading patchlevels within a release (e.g., within 1.8.0). To upgrade with patch files, get all the patch files for higher patchlevels than your current version. For example, if you're running 1.8.0p0 and the latest version is 1.8.0p4, you need patches 1-4. These files are stored at http://ftp.pennmush.org/Source and usually named things like 1.8.0-patch02 (the patch from 1.8.0p1 to 1.8.0p2) or, in some cases, 1.7.6p16-1.8.0p0.patch (the patch from 1.7.6p16 to 1.8.0p0). Each patch file contains instructions at the top explaining how to apply it. FOLLOW THESE! Don't assume they're all the same. After you've applied all the patches and followed all the instructions, you should be good to go. In most cases, you can simply @shutdown/reboot after the final successful compile. If @shutdown/reboot crashes, you'll have to restart again. A.2. Building a new distribution When you're upgrading across release and no patchlevel is provided to make the upgrade (e.g. from 1.7.4p3 to 1.8.0p0), it's often easier to simply build a new distribution following the INSTALL instructions, but with your old configuration stuff. Move your older version of PennMUSH in a directory called oldpenn/, unpack the new one (it will unpack into pennmush/). All of the steps below should be taken before running Configure for the new version: A.2.a. options.h and game/*.cnf You can copy the options.h file and game/mush.cnf file from your old version to the new version. The 'make update' command (run after Configure) will compare your files with the newly distributed ones and tell you about options that have been added or removed. If you have any options defined that the new version doesn't recognize, you'll be asked if you want to retain them (which is safe). If your mush.cnf file is called something else, copy it to mush.cnf in pennmush/game anyway, since that's the file that gets updated. Then make a link to that file called whatever.cnf if you want to use that. If you've modified the restart script, you'll have to decide if your modified script is still appropriate, or modify the distributed game/restart script again as you like it. The latter is encouraged. You can also copy your old game/access.cnf, game/sitelock.cnf, and game/txt/*.txt files into the appropriate locations. You may wish to do the same thing for game/restrict.cnf, but you should compare it to the new version, as restrictions that may formerly have been compiled into the server may now be specified in restrict.cnf instead. A.2.b. src/*local.c You should copy local.c, cmdlocal.c, and funlocal.c from oldpenn/src to pennmush/src if you want to retain this local code. Of course, it may not still work, but it's quite likely that it will. If you don't have any such code, you can skip this step. A.2.c. Databases This MUSH version should read databases along the main branch of MUSH evolution -- TinyMUD, vanilla TinyMUSH up to 2.0, MicroMUSH, and all Pern/PennMUSH versions. If you need to convert a TinyMUSH 2.0 database, please contact Amberyl, and she'll mail you an extension to 2.0 that will dump a 1.50-readable flatfile. You're probably out of luck with databases for TinyMUSH 2.2 and later. Be sure that your options.h settings correctly reflect the type of password encryption that was used on your database. The default has changed to SHS, so if your db used crypt(3) encryption, be sure you set the appropriate definition in options.h. *** If you are upgrading from 1.7.4 (or earlier) to 1.7.7 (or later), *** you must first load your old database under PennMUSH 1.7.6 and *** then dump it, and load this converted database under your *** target version of PennMUSH. PennMUSH 1.7.7+ can no longer read *** 1.7.4 databases. ============================================================================ B. PennMUSH with a few hacks When you have only a few local hacks outside of the src/*local.c files, you can often patch up using the patch file method discussed above. Alternatively, you can build a new version and reapply your changes. One small exception is upgrading from a version that used the old flag system to one that uses the new flag system (post-1.7.7p5), if you've added flags or toggles. You probably had an #define in hdrs/flags.h for your flag's bit value. This now should be moved to hdrs/oldflags.h; you should leave in the table entry in src/flags.c. If you set up a macro for testing your flag in hdrs/mushdb.h, you'll need to change it to use the has_flag_by_name() function - see the many examples in that file. If this isn't suitable (you're crossing releases or your hacks are too many for this to work cleanly), see below. ============================================================================ C. PennMUSH with a lot of hacks If you've seriously hacked your server source code, you're on your own in terms of keeping up with new patchlevels. Some people apply patchfiles and fix the rejected hunks. A better approach is probably that described in the Guide for Gods, and involves creating a set of patches from the distributed old version of pennmush (e.g. 1.7.4p16) to your hacked version of pennmush (e.g. 1.7.4p16 with hacks), and then applying those patches to the new version of PennMUSH (e.g. 1.8.0p0) to create a hacked version thereof. If some patch hunks fail, you'll have to apply them manually. Probably the best approach is to keep all multiple versions of the code (old distributed, old hacked, new distributed, new hacked) under a source code control system like prcs that can merge changes between versions. See the Guide for Gods. ============================================================================ IMPORTANT NOTES FOR THOSE UPGRADING TO 1.8.0 FROM 1.7.6: * Softcode gotchas: * Wizards (other than God) and royalty are no longer treated as No_Pay unless the No_Pay power is explicitly set on them, although they can still give (themselves or others) as many pennies as they wish. This helps stop runaway wizards in the queue (they'll run out of cash like anyone else). To get the old behavior back, @power your admin No_Pay. You probably want to @power any globals that use search(), children(), mail*stats(), etc, No_Pay as well. * @desc can no longer be gotten remotely without privileges. @desc on privileged objects can now be evaluated by mortals. * @adisconnect is triggered on every disconnection, partial or full. This mirrors the behavior of @aconnect. Use %1 (the number of remaining connections) to distinguish between partial and full disconnects in @adisconnect code. * Players can no longer be set CHOWN_OK. If you have existing CHOWN_OK players, you probably want to unset this from them, or the results will be confusing (they'll continue to appear to have the flag, even though it won't be testable or settable or clearable; this is desired behavior). * New HEAVY admin flag, prevents an object from being teleported by a mortal between two containers they own. Admin without this flag CAN be teleported. * Hardcode/db/startup gotchas: * After each @startup is enqueued (during startup or @restart/all), we immediately run up to 5 queue cycles. This allows, e.g., God's @startup to up to five levels of @dol/@tr/@switch/etc and still have the queued code run ahead of other startups. This requires that you keep God's dbref as #1. * netmush is now started with only a single argument - the path to the configuration file. The error log file (typically game/netmush.log is now configured in mush.cnf. * CHAT_SYSTEM option removed. If you don't want to use the chat system, use restrict.cnf to disable @channel, @chat, etc. * USE_MAILER and MAIL_ALIAS options removed. If you don't want to use the @mail or @malias systems, use restrict.cnf to disable the associated commands. * QUOTA, EMPTY_ATTRS, and FUNCTION_SIDE_EFFECTS options are now runtime options, instead of compile-time. * SINGLE_LOGFILE option removed, and log filenames are now runtime options. You may now give the same name to multiple log files and get a more fine-grained version of the same effect. * src/Makefile is now autobuilt from src/Makefile.SH. IF you use local hacks that require src/Makefile, this is likely to be a problem for you. You'll want to start patching Makefile.SH instead. * The new code can no longer read databases created by versions of Penn before 1.7.5p0. If you need to do this, load it in 1.7.6, shutdown, and use that database. * PROFILING #define for use when profiling the code (surprise). This just disables the CPU timer. * help-like commands without arguments now use the command name as the argument. E.g. 'news' now looks for topic 'news', instead of 'help'. If not found, we fall back on help. * Mail messages now track not only the dbref of the sender but the sender's creation time, so messages from dbrefs that have been nuked and recreated can be distinguished from messages from the original sender. This modifies the maildb and make it not usable with older versions. All existing @mail is grandfathered in, and can't be tracked this way.