Verse Modeling Language tools for object serializing
License
GPL-2.0, BSD-3-Clause licenses found
Licenses found
GPL-2.0
COPYING.loader
BSD-3-Clause
COPYING.saver
versenaut/vml
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> <html> <head> <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> <style type="text/css"> h1.title { text-align: center; } p.author { text-align: center; } pre.shell { background-color: #ddddff; border-color: black; padding: .5em; border-style: solid; border-color: black; border-width: thin; } span.opt { font-family: monospace; } span.var { font-style: italic; //font-weight: bold; } </style> <title>About the VML Tools</title> </head> <body> <h1 class="title"> About the VML Tools </h1> <p class="author"> Author: Emil Brink, PDC, KTH 2006. For <a href="http://www.uni-verse.org/">Uni-Verse</a>. </p> <h1>Introduction</h1> <p> This text briefly describes the "saver" and "loader" Verse clients. The purpose of these programs is to create and use disk files holding Verse content, in textual format. This format, called VML ("Verse Modeling Language"), is based on XML. </p> <p> The tools were written in parallel by two authors; the saver by Eskil Steenberg and the loader by Emil Brink. They are collected here since they are functionally very related, and one is not very useful without the other. </p> <h1>Licensing</h1> <p> Licensing for these applications is like this: the loader code, since it depends on the GPL code from Purple, must be GPL too. The saver, which uses only the Enough and Verse libraries (both BSD) is BSD. The license texts are in COPYING.loader </p> <h1>Dependencies</h1> <p> This section talks about the dependencies for the two tools. It is <strong>only</strong> of interest to people who want to compile the tools from scratch. If you have pre-compiled ("binary") versions of the tools already at hand, feel free to ignore this whole section. </p> <p> Technically, the tools are widely different, owing to their different authors but also to the different functionality. </p> <p> Both tools naturally depend on Verse at the core; to build either, you will need to have the header ("verse.h") and library ("libverse.a" on Linux systems) in a location indicated by the VERSE variable in the Makefile. </p> <h2>Saver Dependencies</h2> <p> The saver depends on the "Enough" Verse data storage library, which is also by Eskil. It is available in the "quelsolaar" CVS module, please look it up if you do not already have it. The Makefile will need to be edited to point to a location for the required header and library files. </p> <h2>Loader Dependencies</h2> <p> The loader, on the other hand, depends on the general-purpose utility code developed for the <a href="http://purple.blender.org/">Purple</a> scripting environment. This is another Verse project, and is in the "purple" <a href="http://projects.blender.org/viewcvs/viewcvs.cgi/purple/?cvsroot=verse">CVS module</a>. Purple is here simply used as a source of fairly well-tested, basic utility code, to get up and running the actual client as quickly as possible. </p> <p> The following files are part of the Purple codebase (the extension ".[ch]" means that there is both an implementation and a header file with the indicated base name): </p> <dl> <dt><code>dynstr.[ch]</code></dt> <dd>Dynamic (growable) strings.</dd> <dt><code>list.[ch]</code></dt> <dd>Doubly linked list.</dd> <dt><code>log.[ch]</code></dt> <dd>Basic error/warning logging.</dd> <dt><code>mem.[ch]</code></dt> <dd>Memory allocation.</dd> <dt><code>memchunk.[ch]</code></dt> <dd>Chunked memory allocation.</dd> <dt><code>strutil.[ch]</code></dt> <dd>Various string utility functions.</dd> <dt><code>xmlnode.[ch]</code></dt> <dd>Simple XML parser.</dd> </dl> <p> If possible in your environment, it might be a good idea to check out the entire Purple module in a separate directory, and replace the above files with symbolic links into Purple. That way, you will only have one version of each of the shared files, and any updates (which are likely to happen to the Purple side first, perhaps exclusively) will not be missed. You can do this by editing the Makefile variable PURPLE to point at your local copy of the Purple code, and then doing "make purplelink" to replace the files with symbolic links to Purple. </p> <p> Building the loader is easy, as illustrated by the included Makefile. </p> <h1>Usage</h1> <p> Once you have the tools built, using them is simple. </p> <h2>Saver Modes</h2> <p> The saver has two completely different <i>modes</i> in which it can operate. The differences between the two modes affect how long the saver runs, and the format of the output it creates. </p> <p> The modes are: </p> <ul> <li><a href="#oneshot">One-shot</a> <li><a href="#cont">Continuous</a> </ul> <p> The command-line option <code>-1</code> ("minus one") selects which mode to use: if specified, the saver runs in one-shot mode. If omitted, it runs in continuous mode. </p> </p> <h3><a name="oneshot">One-Shot Mode</a></h3> <p> Activated by including the <code>-1</code> option on the command line. </p> <p> In this mode, the saver runs once, and creates a (possibly very big) single VML file containing a snapshot of the entire state of the server, as it was when the saver began saving. You can control the amount of time the saver spends downloading, before it starts to save, with the <code>-i <i>n</i></code> option. Since it is not possible to say when the scene is "finished" downloading, this is all you can do. You can set the name of the output file with the <code>-f <i>name</i></code> option. After writing the single file, the saver will exit. </p> <h3><a name="cont">Continuous Mode</a></h3> <p> Default, does not require any special option to enable. </p> <p> This mode is meant for more serious back-up and roll-back of a server's contents. In it, the saver runs for a prolonged duration (minutes, hours, or days), creating new snapshots of the server's contents from time to time. <p> In continuous mode, the saver's actions are controlled by two further time intervals: </p> <ul> <li>The change period, set by the <code>-c <i>n</i></code> option, controls how many seconds after the last change the saver will do a new snapshot. <li>The override period, set by the <code>-C <i>n</i></code> option, controls how many seconds may at most pass between snapshots, even if changes occur all the time. </ul> <p> The general idea is to create an initial snapshot that includes all the server's contents, then every once in a while (as set by the <code>-c</code>) option, create an updated snapshot holding only the nodes that changed since the last one. In case the data is changing all the time, this would be starved from saving at all, which is why the second period (set by the <code>-C</code> option) exists, and makes sure that the data is saved regularly. </p> <p> In continuous mode, the saver saves data in the same VML format as used otherwise, but splits it into multiple files. In general, there's one top-level file for each snapshot, and a number of separate files describing each node in the snapshot. The files are linked by use of <a href="http://www.w3.org/TR/2003/WD-xinclude-20031110/">XML Inclusions</a> from the top-level file. </p> <p> For example, consider a server holding two object nodes, and nothing else. Let's call the nodes "foo" and "bar". An initial snapshot would result in the following files being output: </p> <pre class="shell">dump_20061108_141517Z.vml object/foo_20061108_141517Z.vml object/bar_20061108_141517Z.vml </pre> <p> Here, the <tt>dump_20061108_141517Z.vml</tt> file is the top-level file, which is saved out in the directory from which the saver was called. The timestamp consists of two parts, a date and a time, separated by an underscore. </p> <p> The date part is in <a href="http://en.wikipedia.org/wiki/ISO_8601">ISO 8601</a> format (i.e. YYYYMMDD), as is the time (HHMMSS). The trailing 'Z' is part of the timestamp, and indicates that it is in the UTC timezone. </p> <p> Further, please note that the per-node files are in a directory named after the node type ("object") in this case, since the two nodes were object nodes. If we were to look inside the top-level VML file, we would see something like this: </p> <pre class="shell"><?xml version="1.0" encoding="latin1"?> <vml version="1.0" xmlns:xi="http://www.w3.org/2001/XInclude"> <xi:include href="object/foo_20061108_141517Z.vml"/> <xi:include href="object/bar_20061108_141517Z.vml"/> </vml> </pre> <p> Basically, it just wraps two <code>xi:include</code> elements with a top-level <tt>vml</tt> element, to make the result as a whole (once the includes are performed) a valid VML file. </p> <p> At this time, if we were to somehow modify the node named "bar", at the next snapshot time, we would get: </p> <ul> <li>A new top-level snapshot, with the current time in its filename. <li>A new "bar" snapshot in the <code>objects/</code> directory. </ul> <p> The new top-level snapshot would include the new "bar" node, but would continue to include the <b>old</b> version of the "foo" node, since it's still the most recent, the node hasn't changed between the two snapshots. </p> <h2>Using the Saver</h2> <p> The saver is typically called from a command line, like this (in one-shot mode): </p> <pre class="shell">~> ./saver -1 -i 30 -f test.vml </pre> <p> This will save the file only once and then exit (the "<span class="opt">-1</span>" option), after first waiting 30 seconds for data to download (the "<span class="opt">-i 30</span>"). The file will be named <tt>test.vml</tt>, as indicated by the "<span class="opt">-f test.vml</span>" option. There are other options, give it a "<span class="opt">-h</span>" option to display them. </p> <p> In continuous mode, we could use a command line like the following to start it off: <pre class="shell">~> ./saver -i 20 -c 30 -C 600 </pre> This would check, every 20 seconds, if 30 seconds have passed since the last time any node changed. If so, it would trigger a new snapshot. If no new snapshot has been saved, and it is more than 600 seconds (10 minutes) since the last snapshot, a new snapshot will be generated anyway. In this mode, the saver will continue running until its process is killed. </p> <h3>All saver Options</h3> <p> These are all the options currently supported by the saver: </p> <dl> <dt><span class="opt">-h</span></dt> <dd>Shows a list of available options.</dd> <dt><span class="opt">-n <span class="var">name</span></span> <dd>Set user name to use when logging into Verse.</dd> <dt><span class="opt">-p <span class="var">pass</span></span> <dd>Set password to use when logging into Verse.</dd> <dt><span class="opt">-a <span class="var">address</span></span> <dd>Set Verse server address to connect to.</dd> <dt><span class="opt">-f <span class="var">filename</span></span> <dd>Set filename for output.</dd> <dt><span class="opt">-l</span> (lower case letter L) <dd>Filter out object nodes without links or tags.</dd> <dt><span class="opt">-1</span> (the digit one) <dd>Save only once, then exit.</dd> <dt><span class="opt">-i <span class="var">interval</span></span> <dd>Sets number of seconds spent downloading before saving (or attempting to save, in continuous mode).</dd> <dt><span class="opt">-c <span class="var">n</span></span> <dd>In continuous mode, save un-changed nodes every <span class="var">n</span> seconds.</dd> <dt><span class="opt">-C <span class="var">n</span></span> <dd>In continuous mode, save nodes every <span class="var">n</span> seconds, even if changing.</dd> </dl> <h2>Using the Loader</h2> <p> To upload the file <tt>test.vml</tt>, created by the saver above, one would issue a command like this: <pre class="shell">~> ./loader -ip=verse.example.org:4711 test.vml </pre> <p> The <tt>-ip=</tt> option is used to set the IP address of the target Verse server. The port number is optional, if omitted the default Verse port is used. All other arguments are assumed to be filenames of VML files, which will be uploaded individually. </p> </body> </html>
About
Verse Modeling Language tools for object serializing
Resources
License
GPL-2.0, BSD-3-Clause licenses found
Licenses found
GPL-2.0
COPYING.loader
BSD-3-Clause
COPYING.saver
Stars
Watchers
Forks
Packages 0
No packages published