The UruDistro.xml file

Announcements and discussion regarding Chacal's UruDistro

Moderator: Chacal

The UruDistro.xml file

Postby Chacal » Tue Jul 07, 2009 2:17 pm

The UruDistro.xml file is included in each distribution. It can be manually edited by the author, and I'm planning to write a script to generate parts of it from the contents of the distribution folder.

The user's install script will parse the xml file, which will fail if the file does not comply with the following DTD, which is part of the user's UruDistro installation:

UruDistro DTD Show Spoiler


The script will then perform a sanity check on the distro, making sure all needed files are included, all target files exist in the Uru folder, and the data in the xml file is coherent.

Here's an example xml file:

Example UruDistro.xml file Show Spoiler


The first part of the file describes the distribution. This information will be presented to the user so he can confirm he wants to install it:
confirmation dialog Show Spoiler



distro id
Each distribution should have a unique id number, although the system will work fine otherwise.
I don't expect hundreds of distros, so it should be easy to pick a unique number.
Numbers starting with "000000" should be reserved for internal testing.

version
The version number of your distribution.

name
A short name for your distro.

author
Author's real name or alias. Ideally, this would include your GoW alias for support purposes.

date
Date this version was released. No specific date format is required.

<description>This distro ...</description>
Include as much pertinent information here as you can. Especially, describe the changes enough so the user can make an informed decision about trying it or not. Also specifi if any previous version should be uninstalled before installing this one.

The rest of the file describes your changes for the install script.

<file>
One <file> node can exist in the xml file.
This node lists files to be deleted (delobj) or added (addobj) to the user's game folder. Files to be added MUST all be included in your distro or the install script's sanity check will fail and the script will refuse to perform any change at all. Normally a distribution should not delete files from the user's game folder, this is more for the uninstall script. The "type" attribute is important, as it tells the install script where to copy the file.

<sdl id="Fens" statedesc = "Fens">
Several <sdl> nodes can exist in the xml file.
Each node lists changes to one SDL file. The "id" parameter MUST be the name of an existing SDL file otherwise the install script's sanity check will fail. The "statedesc" attribute must exist otherwise the xml validation will fail, and should be the name of an existing STATEDESC section in the file, otherwise no change will be applied on the file. In all Cyan files, this attribute has the same value as the name of the SDL file. The install script will copy the last version of this STATEDESC block from the user's file, increment the version number and add or replace the SDL variables specified. Normally a distribution should not delete SDL variables, this is more for the uninstall script.

<age id="Fens">
Several <age> nodes can exist in the xml file.
Each node lists changes to one .age file. The "id" parameter MUST be the name of an existing .age file otherwise the install script's sanity check will fail. The install script will add the specified pages to the user's .age file, replacing them if they already exist. Normally a distribution should not delete pages, this is more for the uninstall script.

<fni id="Fens">
Several <fni> nodes can exist in the xml file.
Each node lists changes to one .fni file. The "id" parameter MUST be the name of an existing .fni file otherwise the install script's sanity check will fail. The install script will add the specified settings to the user's .age file, replacing their old values if they already exist. Normally a distribution should not delete settings, this is more for the uninstall script.

<prp id="Fens_District_mainRoom" scenenode="Fens_District_mainRoom">
Several <prp> nodes can exist in the xml file.
Each node lists changes to one .prp file. The "id" parameter MUST be the name of an existing .prp file otherwise the install script's sanity check will fail. The "scenenode" parameter must be included if any change is made to a plSceneObject.
-<delobj> The "id" and "type" attributes should reference a unique, existing object in the prp. The install script will try to delete the object by invoking the "PrpMod" libPlasma tool with those parameters. If "type" is "plSceneObject", then the "scenenode" attribute must contain the name of the prp file's plSceneNode object. Normally a distribution should not delete objects, this is more for the uninstall script.
- <addobj> The "id" and "type" attributes should reference a unique object in the prp. If the object exists it will be replaced. The "data" attribute MUST contain the filename and extension (but not the path) of a file included in the distro folder otherwise the install script's sanity check will fail. The install script will try to add the object by invoking the "PrpMod" libPlasma tool with those parameters. If "type" is "plSceneObject", then the "scenenode" attribute must contain the name of the prp file's plSceneNode object.
Last edited by Chacal on Wed Jul 08, 2009 2:43 pm, edited 4 times in total.
Chacal


"The weak can never forgive. Forgiveness is an attribute of the strong."
-- Mahatma Gandhi
User avatar
Chacal
 
Posts: 2508
Joined: Tue Nov 06, 2007 2:45 pm
Location: Quebec, Canada

Re: The UruDistro.xml file

Postby Chacal » Tue Jul 07, 2009 4:46 pm

Comments, suggestions, etc, are always appreciated.
Chacal


"The weak can never forgive. Forgiveness is an attribute of the strong."
-- Mahatma Gandhi
User avatar
Chacal
 
Posts: 2508
Joined: Tue Nov 06, 2007 2:45 pm
Location: Quebec, Canada

Re: The UruDistro.xml file

Postby Robert The Rebuilder » Tue Jul 07, 2009 7:07 pm

Looks great! I would add one more tag:


<python pak="python.pak" file="psnlBookshelf.py">

Specifies which Python file (in which PAK file) is to be modified. This is followed by a Unix diff of the two files, to be applied as a patch.
Can we rebuild it? Yes, we can - here's how.

MOULagain KI# 1299

Myst Movie coming soon - spread the word!
User avatar
Robert The Rebuilder
 
Posts: 1383
Joined: Sat Sep 29, 2007 7:24 am
Location: Virginia, US

Re: The UruDistro.xml file

Postby Chacal » Tue Jul 07, 2009 11:23 pm

Added to to-do list.

The DTD for the xml file is now published in the initial post.
The great thing about using a DTD is that the XML parser will check the syntax and contents of every xml file against the DTD, so I don't have to code this check myself.
This protects the user against clumsy or stupid authors. Or against admiral Ozzel, who is as clumsy as he is stupid.
Chacal


"The weak can never forgive. Forgiveness is an attribute of the strong."
-- Mahatma Gandhi
User avatar
Chacal
 
Posts: 2508
Joined: Tue Nov 06, 2007 2:45 pm
Location: Quebec, Canada

Re: The UruDistro.xml file

Postby diafero » Wed Jul 08, 2009 9:00 am

What I find confusing is the "id" property of the "addobj" and "delobj" tags - what exactly is it used for?
Besides, it looks like a very clean design, great :)
I prefer e-mails to "diafero arcor de" (after adding the at and the dot) over PMs.

"Many people's horizon is a circle with a radius of zero. They call it their point of view."

Deep Island Shard | Offline KI
diafero
Deep Island Admin
 
Posts: 2966
Joined: Mon May 05, 2008 5:50 am
Location: Germany

Re: The UruDistro.xml file

Postby Chacal » Wed Jul 08, 2009 9:27 am

It is important that each action can be uniquely referred to, so that a script can find it again using an xpath.
For example, this xpath refers to a single action:
/distro/age[@id='"Fens"']/addobj[@id="Test_Page_Fens_1"]

This was more evident in the old xml structure I used. The current structure does not follow the best practice, because attributes should only store metadata, and elements should store data. In the old structure, instead of:

Code: Select all
   <sdl id="Fens" statedesc="Fens">
      <addobj id="FensTest1" data="VAR BOOL    FensTest1[1]    DEFAULT=0 DEFAULTOPTION=VAULT"/>
   </sdl>


I had:
Code: Select all
   <sdl id="Fens">
      <statedesc>Fens</statedesc>
      <addobj id="FensTest1">
          <data>VAR BOOL    FensTest1[1]    DEFAULT=0 DEFAULTOPTION=VAULT</data>
      </addobj >
   </sdl>


That way it is easier to see that the id attributes are metadata, they don't contain data.

I only use the new structure because it is easier for the author to edit manually.

Also, in some cases it may be important to have the name of the object or variable without having to extract it from the data part. Such is the case for fni and prp, where id is the name of a variable or an object.
Chacal


"The weak can never forgive. Forgiveness is an attribute of the strong."
-- Mahatma Gandhi
User avatar
Chacal
 
Posts: 2508
Joined: Tue Nov 06, 2007 2:45 pm
Location: Quebec, Canada

Re: The UruDistro.xml file

Postby diafero » Wed Jul 08, 2009 11:33 am

But how can an object from an ade or sdl file be removed by its id? Especially ids like "comment1" can not be extracted from the result itself.
I prefer e-mails to "diafero arcor de" (after adding the at and the dot) over PMs.

"Many people's horizon is a circle with a radius of zero. They call it their point of view."

Deep Island Shard | Offline KI
diafero
Deep Island Admin
 
Posts: 2966
Joined: Mon May 05, 2008 5:50 am
Location: Germany

Re: The UruDistro.xml file

Postby Chacal » Wed Jul 08, 2009 12:15 pm

I'm not talking about the result here. A script might have to refer to a particular element in the XML file (not the game file), which is why I usually put ids in my elements.

For example, I need the id to pass as a parameter to worker functions. If I want to remove the "comment1" object from the SDL file, the script will pass this id to a function, which will fetch the actual data from the XML file, find it in the SDL file and kill it.
Chacal


"The weak can never forgive. Forgiveness is an attribute of the strong."
-- Mahatma Gandhi
User avatar
Chacal
 
Posts: 2508
Joined: Tue Nov 06, 2007 2:45 pm
Location: Quebec, Canada

Re: The UruDistro.xml file

Postby Chacal » Wed Jul 08, 2009 3:09 pm

I updated the DTD and the example xml with minor changes in the sdl delobj element. This is for the uninstall functionality.

Here's my strategy for uninstalling: while installing, for each change, find the opposite of the change, and write it in a new uninstall.xml file. After installation, the user can uninstall by simply running the install script again, this time parsing uninstall.xml.

This seems simple and elegant to me. The install script can even look for uninstall.xml, and if it exists ask the user if he wants to uninstall the distribution.

Now we have to find the opposite changes.

file delobj
install: delete a file from the game folder
uninstall: copy a backup of old file to the game folder

file addobj
install: copy a file from the distro folder to the game folder
uninstall: delete the file or copy a backup of old file to the game folder

age, fni delobj
install: delete a line from the file (doesn't make much sense, but you never know)
uninstall: add or replace the old line back

age, fni addobj
install: add or replace a line in the file
uninstall: add or replace the old line back

prp delobj
install: delete an object from the prp file
uninstall: add or replace the old object back

prp addobj
install: add or replace an object in the prp file
uninstall: delete object, add the old object back if there was one

sdl delobj
install: add a new version of the last statedesc block, delete a line from it (makes no sense at all so not implemented)
uninstall: not implemented

sdl addobj
install: add a new version of the last statedesc block, add or replace a line in it
uninstall: delete the version we added

From the above, it is clear that uninstallation can only be prepared at installation time.

So here finally are the steps the install script must do to prepare the uninstall.xml file:

file delobj: copy file to backup file, add an addobj
file addobj: copy old file to backup file if it exists, add a delobj
age, fni delobj: add an addobj with old line
age, fni addobj: add an addobj with old line if exists
prp delobj: extract object to backup, add an addobj
prp addobj: extract object to backup, if no error add an addobj else add a delobj
sdl delobj: N/A
sdl addobj: add a delobj with "version" and "data" with our version number

A question I'm asking myself: this is simple because both xml files use the same DTD.
Since delete operations (except for prp delobj) make no sense in a distribution, should I forbid their use in the install xml for security purposes, and allow then only for the uninstall xml? I could have a different DTD for each xml file.

But you never know, maybe for some strange reason someday it will become necessary to delete things from the game.

Comments, suggestion, etc.
Chacal


"The weak can never forgive. Forgiveness is an attribute of the strong."
-- Mahatma Gandhi
User avatar
Chacal
 
Posts: 2508
Joined: Tue Nov 06, 2007 2:45 pm
Location: Quebec, Canada

Re: The UruDistro.xml file

Postby diafero » Thu Jul 09, 2009 9:18 am

Currently I do not know of a situation in which I had to remove a line from an age or sdl file. For fni files someone might want to remove parts of the fog definition, though I don't see why that should be done by a distribution. For the sake of completeness, and if it is not too much work, I would allow it - even for SDL files as some weird people might expect that behaviour. It does not make less sense to remove a VAR from an SDL file than to remove a line from an age file, so if the one is possible, the other should be, too.
I prefer e-mails to "diafero arcor de" (after adding the at and the dot) over PMs.

"Many people's horizon is a circle with a radius of zero. They call it their point of view."

Deep Island Shard | Offline KI
diafero
Deep Island Admin
 
Posts: 2966
Joined: Mon May 05, 2008 5:50 am
Location: Germany

Next

Return to UruDistro

Who is online

Users browsing this forum: No registered users and 1 guest