Rotating configs for advanced scenarios

Aha, finally to the end. This post, like the 5th post, is largely optional. One of the restrictions of our development environment is that, while our senior admin is active enough to make requests of, none of our active coders have root server-level access. Within this context, our nightly update process runs Doxygen, and we aren't currently set up to run alternative nightly update scripts. Instead, our primary topic here will be using MUD-side configuration rotation. I won't spend time discussing the actual scheduling of these, under the assumption that most muds probably have some custom method of implementing time-based code execution. We have yet to implement rotating configurations ourselves, so this post isn't going to contain much source code (until we start rolling this functionality out, at which time we'll update the post).

The structure of this post is as follows:

  • Uses for configuration rotation
  • Implementation

Uses for configuration rotation

The best question is why we really need to rotate configurations in the first place. The vague answer is that Doxygen is very flexible software with a really wide array of processing options useful for different types of tasks. The more specific answer would be to identify a few things we can do if we're rotating configs:

  1. Condensed PDF guides for new builders/coders that can be packaged for builders who don't yet know how to navigate the documentation system, containing only the essential guides.
  2. Provide exhaustive HTML documentation without the resource cost of generating it every day.
  3. Minimize the amount of work the server does for most daily runs.
  4. Rare full parse of the mudlib

Implementation

We're going to fast-track the first three of these in our discussion here, because they're focused on putting less strain on the system and have less risk of causing problems when they run. It may be simplest to talk about all three points at once, anyways. In our case we have a custom cron daemon which has a job set to update our doxygen config file about 5 minutes before our nightly update runs. Our first step will be to have a processing order, from most to least important, for our various configs/scenarios. For us this would probably be XML-only, HTML-only, followed by PDF only, but the existence of the list is more important than its order.

Our next step is going to be to write a quick function capable of extracting each input source from the INPUT option of whatever config is selected, and combining it with our list of valid extensions; we should probably go ahead and repeat this process for both our includes and examples directories. This function should probably go ahead and spit out strings we can pass directly to get_dir for the purpose of compiling a list of timestamps. We don't really care about file paths. We're going to run efun.max() on these to find the newest file within the scope of this config's parse. You may need to augment this method if you have recursive directory parsing on within Doxygen. We'll compare the largest timestamp to the timestamp for the index of the type this file is designed to document (e.g. /doxygen/html/index.html) and we'll only run the config if a file is newer than the output. If none of the configs fires, we'll fall back on a barebones config with no inputs and no output types, letting the server save its time.

The largest portion of the task in each of these cases will be cultivating a careful list of inputs tailored to each scenario.

Discussing this elsewhere?
Enter 'link' for a markdown link
or 'tweet <message>' for a pre-populated Tweet :)
Want to subscribe? Enter 'rss' for a feed URL.
>