mirror of
https://github.com/pennmush/pennmush
synced 2026-08-12 22:23:05 -04:00
158 lines
8.7 KiB
HTML
158 lines
8.7 KiB
HTML
<!DOCTYPE html>
|
||
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<meta name="generator" content="pandoc" />
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
|
||
<title>Database Tools</title>
|
||
<style type="text/css">
|
||
code{white-space: pre-wrap;}
|
||
span.smallcaps{font-variant: small-caps;}
|
||
span.underline{text-decoration: underline;}
|
||
div.column{display: inline-block; vertical-align: top; width: 50%;}
|
||
</style>
|
||
<!--[if lt IE 9]>
|
||
<script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
|
||
<![endif]-->
|
||
</head>
|
||
<body>
|
||
<header>
|
||
<h1 class="title">Database Tools</h1>
|
||
</header>
|
||
<nav id="TOC">
|
||
<ul>
|
||
<li><a href="#introduction">Introduction</a></li>
|
||
<li><a href="#building">Building</a><ul>
|
||
<li><a href="#unix">Unix</a></li>
|
||
<li><a href="#windows-using-visual-studio-2017">Windows, using Visual Studio 2017</a></li>
|
||
</ul></li>
|
||
<li><a href="#the-utilities">The Utilities</a><ul>
|
||
<li><a href="#dbupgrade">dbupgrade</a></li>
|
||
<li><a href="#grepdb">grepdb</a></li>
|
||
<li><a href="#pwutil">pwutil</a></li>
|
||
<li><a href="#db2dot">db2dot</a></li>
|
||
</ul></li>
|
||
</ul>
|
||
</nav>
|
||
<h1 id="introduction">Introduction</h1>
|
||
<p>dbtools is a library and set of utilities for examining, transforming, and editing PennMUSH database files. Unless otherwise specified, all programs can work with either uncompressed databases, or ones compressed with gzip (<strong>.gz</strong>) or bzip2 (<strong>.bz2</strong>). Old compress (<strong>.Z</strong>) files are a different format that the compression library used can’t handle.</p>
|
||
<p>Currently, any database generated by PennMUSH 1.7.6 and up <em>should</em> be readable, as well as many older formats. Further testing and compability work is ongoing.</p>
|
||
<p>It does not currently support mail or chat databases.</p>
|
||
<h1 id="building">Building</h1>
|
||
<p>dbtools programs are written in C++, not C like Penn itself. They depend on OpenSSL, and the <a href="https://www.boost.org/doc/libs/1_66_0/libs/iostreams/doc/index.html">boost.iostreams</a> and <a href="https://www.boost.org/doc/libs/1_66_0/doc/html/program_options.html">boost.program-options</a> libraries as well as some header-only boost libraries. The latter can be installed on Ubuntu like systems with <code>sudo apt install libboost-dev libboost-iostreams-dev libboost-program-options-dev</code>, and arch via <code>sudo pacman -S boost</code>. <code>cmake</code> is used for configuration and creating Makefiles.</p>
|
||
<h2 id="unix">Unix</h2>
|
||
<p>To build:</p>
|
||
<pre><code>% cd dbtools
|
||
% cmake -DCMAKE_BUILD_TYPE=Release .
|
||
% make -j4</code></pre>
|
||
<h2 id="windows-using-visual-studio-2017">Windows, using Visual Studio 2017</h2>
|
||
<h3 id="installing-dependencies">Installing dependencies</h3>
|
||
<ol type="1">
|
||
<li><p>Install a git client if not already present.</p></li>
|
||
<li><p>Install <a href="https://github.com/Microsoft/vcpkg">vcpkg</a> if not already present, following the instuctions on that page.</p></li>
|
||
<li><p>Install the following packages if needed (Via <code>.\vcpkg install</code>): <strong>openssl boost-iostreams boost-program-options boost-algorithm boost-container</strong> (This might take a while)</p>
|
||
<p>vcpkg supports both 32-bit and 64-bit targets. You might need to explicitly request the one you want to use (64 bit is suggested), by <code>.\vcpkg install openssl:x64-windows</code> or <code>.\vcpkg install openssl:x86-windows</code>.</p></li>
|
||
</ol>
|
||
<h3 id="actually-building">Actually building</h3>
|
||
<ol type="1">
|
||
<li><p>Open VS 2017.</p></li>
|
||
<li><p><em>File->Open->Folder</em> and select the dbtools directory.</p></li>
|
||
<li><p>Right click on <em>CMakeLists.txt</em> in the Solution Explorer and select <em>Change CMake Settings</em>. This will bring up a file called <em>CMakeSettings.json</em>. It has an assortment of build targets (Like <code>x64-Release</code>), any of which you plan on using needs to be updated to let CMake know about the vcpkg installation. Instructions and an example are <a href="https://vcpkg.readthedocs.io/en/latest/examples/using-sqlite/#cmake">here</a>.</p></li>
|
||
<li><p>Select <em>CMake->Build All</em>.</p></li>
|
||
</ol>
|
||
<h1 id="the-utilities">The Utilities</h1>
|
||
<h2 id="dbupgrade">dbupgrade</h2>
|
||
<p>Read a database in any supported format, and write out the database in the current format.</p>
|
||
<h3 id="options">Options</h3>
|
||
<dl>
|
||
<dt>-z</dt>
|
||
<dd><p>Database is compressed with gzip.</p>
|
||
</dd>
|
||
<dt>-j</dt>
|
||
<dd><p>Database is compressed with bzip2.</p>
|
||
</dd>
|
||
<dt>-i</dt>
|
||
<dd><p>Modify the database file in-place. If not given, the database is printed to standard output.</p>
|
||
</dd>
|
||
</dl>
|
||
<p>If a filename is not given on the command line, standard input is used.</p>
|
||
<h3 id="examples">Examples</h3>
|
||
<p>To upgrade an old, uncompressed database in place: <code>dbtools/dbupgrade -i game/data/outdb</code></p>
|
||
<p>To upgrade an old, compressed database: <code>uncompress -c game/data/outdb.Z | dbtools/dbupgrade | gzip -c > game/data/indb.gz</code></p>
|
||
<h2 id="grepdb">grepdb</h2>
|
||
<p>A smart version of grep: Given a regular expression, searches a database and displays the locations it matches. Potentially looks in object names, lock keys and attribute contents.</p>
|
||
<h3 id="options-1">Options</h3>
|
||
<dl>
|
||
<dt>-z</dt>
|
||
<dd><p>Database is compressed with gzip.</p>
|
||
</dd>
|
||
<dt>-j</dt>
|
||
<dd><p>Database is compressed with bzip2.</p>
|
||
</dd>
|
||
<dt>-i</dt>
|
||
<dd><p>The regular expression is matched case-insensitively.</p>
|
||
</dd>
|
||
<dt>-n</dt>
|
||
<dd><p>Search object names.</p>
|
||
</dd>
|
||
<dt>-l</dt>
|
||
<dd><p>Search locks.</p>
|
||
</dd>
|
||
<dt>-t</dt>
|
||
<dd><p>Search attribute bodies.</p>
|
||
</dd>
|
||
<dt>-a</dt>
|
||
<dd><p>Search all fields. If none of -n, -l, -t are given this is the default.</p>
|
||
</dd>
|
||
</dl>
|
||
<p>One mandatory command line argument is needed: The pattern to search for. If a database file name is not also given, standard input is used.</p>
|
||
<h3 id="examples-1">Examples</h3>
|
||
<p>To search for a dbref: <code>./dbtools/grepdb -z "#1622\\b" game/data/outdb.gz</code> (The <code>\b</code> is a word boundry assertation that stops things like “#16222” from matching.)</p>
|
||
<p>To search for a phrase, ignoring case: <code>./dbtools/grepdb -i "White Rabbit" < game/data/outdb</code></p>
|
||
<h2 id="pwutil">pwutil</h2>
|
||
<p>A replacement for <code>utils/pwutil.pl</code>, this program lets you alter passwords of players. Handy if, for example, you forgot God’s password.</p>
|
||
<h3 id="options-2">Options</h3>
|
||
<dl>
|
||
<dt>-d DBREF | -a</dt>
|
||
<dd><p>Specifies a particular player dbref (Without the #), or <code>-a</code> for all players. One of these two options <strong>must</strong> be given.</p>
|
||
</dd>
|
||
<dt>-p PASSWORD</dt>
|
||
<dd><p>The password to use. The default is <em>hunter2</em>.</p>
|
||
</dd>
|
||
<dt>-c</dt>
|
||
<dd><p>Instead of setting a password, erase it. <code>-ac</code> clears all players passwords.</p>
|
||
</dd>
|
||
<dt>-z</dt>
|
||
<dd><p>The database file is gzipped.</p>
|
||
</dd>
|
||
<dt>-j</dt>
|
||
<dd><p>Database is compressed with bzip2.</p>
|
||
</dd>
|
||
<dt>-i</dt>
|
||
<dd><p>Modify the database file in place. If not given, the modified db is printed to standard output.</p>
|
||
</dd>
|
||
</dl>
|
||
<p>If a filename is not given on the command line, standard input is used.</p>
|
||
<h3 id="examples-2">Examples</h3>
|
||
<p>To reset #1’s password to <em>foobar</em>: <code>dbtools/pwutil -iz -d 1 -p foobar game/data/outdb.gz</code></p>
|
||
<p>To erase every player’s passwords in a new database: <code>dbtools/pwutil -acz game/data/outdb.gz > newdb.gz</code></p>
|
||
<h2 id="db2dot">db2dot</h2>
|
||
<p>Creates a graph of the database’s rooms and exits in the dot language used by <a href="https://graphviz.org">graphviz</a>. Graphviz tools can then be used to visualize the grid, and manipulate the graph first if desired.</p>
|
||
<p>Exits without locks are represented by solid lines, exits with locks by dashed.</p>
|
||
<p>If a room or exit has a <em>COLOR</em> attribute, its value is used as the color for that part of the graph. (TODO: Parse <em>MONIKER</em> attributes?)</p>
|
||
<p>If an exit has a <em>DISTANCE</em> attribute that is an integer, its value is used as the length of that edge (Used by some graphviz utilities like <code>dijsktra</code>).</p>
|
||
<h3 id="options-3">Options</h3>
|
||
<dl>
|
||
<dt>-z</dt>
|
||
<dd><p>Indicates the database is gzipped.</p>
|
||
</dd>
|
||
<dt>-j</dt>
|
||
<dd><p>Database is compressed with bzip2.</p>
|
||
</dd>
|
||
</dl>
|
||
<p>If a filename is not given on the command line, standard input is used. The resulting graph is always printed to standard output.</p>
|
||
<h3 id="examples-3">Examples</h3>
|
||
<p>To create a map of your world: <code>dbtools/db2dot -z game/data/outdb.gz | dot -Tsvg > world.svg</code>. It might look like <img src="world.svg" alt="this sample" />.</p>
|
||
<p>To limit the output to only rooms reachable from #0: <code>dbtools/db2dot -z game/data/outdb.gz | ccomps -X room0 > grid.dot</code></p>
|
||
</body>
|
||
</html>
|