[Gtkradiant] design doc - BSP monitoring

[Timothee Besset]

Ok, this is taken from discussions with Spog about BSP process, and the
past history with Q3Build / GtkBuild.

Intro:
------

A few highlights on the common issues we've seen around compiles:

- heterogeneous tools. To the exception of Q3/RTCW's unified q3map
compiler, each game is using it's own compile tools with some specifics
like command line options, and various other problems. The project epairs
and the command expansion system can barely deal with this anymore.

- long compile times, background compile. That was the purpose of
Q3Build/GtkBuild. Final compiles of a map are taking a lot of time, and
the compile process should be made independent of the editor run. i.e.
have compiles running independently of the editor.

- monitoring, integration with the production cycle. Following the status
of the compilation, being able to debug compile errors easily, and other
steps like running the engine auto-magically after compile are important.

Objectives:
-----------

Tools heterogeneity: 

We need more flexibility in the way we describe and manipulate the
available commands. Ideally the end-user should be able to tweak the
commands himself. A user interface is not required though, but at least
some clear XML file format.

Background compiles:

The compiling module should be as independant as possible. We still want
to be able to produce shell scripts or .bat for a completely standalone
compilation. But for other situations we want to be able to shutdown the
editor without killing an ongoing compile. That would mean the BSP module
in GtkRadiant core would be working as an interface to a standalone app,
in charge of the build.

Implementation proposal:
------------------------

Compilation command can be decomposed into an arbitrary succession of
steps. The description of the steps has been done in project epairs so
far, we need to go one step further in terms of functionality, and write
those in XML.

Several essential things:

- The step command to execute. This can be an external program to execute,
or an internal editor command (such as sleep/wake).

- Various parameters about the command, such as wether or not it is
monitored, etc. (also, if return condition should be checked and abort the
compilation).

- Variable expansion. $fs_basepath etc. very basic syntax, $ before a var
identifier

- General configuration. We have some general toggles such as 'monitor the
compile', or 'run engine after compile'. Monitoring for instance, we can
have a $monitor_conf variable, that gets expanded to nothing if monitored
is off. But this doesn't apply to running the engine for instance.

- Capture console output. For non-monitored commands, we may want to
capture the console output instead. If someone has some reliable win32
code that can do that, I am interested.

Sample XML to work from:

<step name="engine" enable="$do_engine">
  <step name="radiant_sleep" enable="$do_sleep" type="internal"/>
  <step name="run engine">$engine +set sv_pure 0 +devmap $map</step>
  <step name="radiant_wake" enable="$do_sleep" type="internal"/>
</step>
<command name="Full compile (BSP/VIS/LIGHT)">
  <step name="BSP">$gametools$tool -fs_basepath $fs_basepath ...</step>
  <step name="VIS">..
  ..
  <step name="engine"/>
</command>
<command name="BSP only">
  ..

a few notes about that XML chunk:

- there is a <step> outside of a command, so that we can recall it by name
and use it several times
- we can enable/disable a step with the "enable" prop
- we can put several steps inside a single one for easy recall (this may
have to be reworked)
- this allows for an unlimited number of commands, with an unlimited
number of steps

I think the basics are described. Some things might change in the design,
but the general idea is there.

TTimo