XRDUA Files

Instructions for users:
-----------------------

If you just want to use XRDUA than it will be easier to download
xrdua_vx-x-x-x.zip from SourceForge or click on "Download" on the XRDUA homepage
(xrdua.ua.ac.be). The zip file contains a SAVE file that runs under the IDL 
Virtual Machine (no license required) on any OS IDL supports.

If you want the program setting file (xrdua.ini) to be saved in another
directory than the program directory, add the variable "xrduadir" to the
environment: 
Windows: Control Panel > System > Advanced > 
             Environment Variables > User variables 
Linux: add "setenv xrduadir ..." or "export xrduadir=..." to a shell startup
       or login script.

On Linux it might also be handy to run INSTALL (as root) to avoid having to
type "idl -vm=xrdua.sav" every time you want to run it and to make sure each
user has his own xrdua.ini settings file. Typing "xrdua" on the command line
will start XRDUA.

Instructions for developers:
----------------------------

You will need:
	1. IDL (7.0 or higher to benefit from the workbench, i.e. IDL's IDE)
	2. BaZaar
	3. Subscription to the XRDUA SourceForge project

Setup an IDL workspace and add the XRDUA project:
	1. Create an IDL workspace or use an existing one by starting the IDL
	   workbench which will prompt you for a workspace name
	   (e.g. .../workspace). Alternitavely you can do this from within the
	   IDL workbench: "File > Switch Workspace > Other..."
	2. Change following workspace settings in the IDL workbench:
	   - disable "Window > Preferences > IDL > Editor
	                 > Insert spaces for tabs"
	   - "Window > Preferences > IDL > Editor > Displayed tab width" = 4
	   - add the project directory to "Window > Preferences > IDL > paths"
	     (checkbox checked)
	3. Make a project subdirectory in this workspace by branching it from
	   the SourceForge branch:
	   bzr branch bzr+ssh://USERNAME@xrdua.bzr.sourceforge.net/bzrroot/xrdua/xrdua .../workspace/xrdua
	4. Add a "New IDL Project" to the IDL workspace. Give it the name
	   "xrdua". Don't use the "Create the new project from an existing
	   directory" option.
	5. Change following project properties in the workbench:
	   - disable "Project Properties > IDL Project Properties
	                 > Update IDL path"
	   - "Project Properties > IDL Project Properties > IDL Build Properties
	                 > Use a custom build command" = @compile
	   - disable "Project Properties > IDL Project Properties
	                 > IDL Build Properties > Create a save file"

Compile XRDUA:
	a. "Project > Build Project" or click the "Build Project" icon in the
	   toolbar
	b. or type "@compile" on the command line

Run XRDUA:
	a. "Run > Run project" or click the "Run Project" icon in the toolbar
	b. or type "xrdua" on the command line

Make a runtime version (i.e. a SAVE file) that will run under IDL's virtual
machine on any IDL supported OS:
	Type "@build" on the command line.

Adding functionality to XRDUA:
	1. All new source files should be added to the "./core" directory.
	2. Make sure that each file starts with a copy of what's in ./FILEHEADER
	3. The name of a new source file should be added to
	   "./build/compilecore.pro" which determines which files should be
	   compiled and in which order. 
	4. A short description of the functions and procedures included in the
	   new source file should be added in dev.pro
	5. The version number should be increased using "@xvmajor", "@xvminor",
	   "@xvrevision" or "@xvbuild". You need BaZaar to use them.
	   In principle, in subsequent releases, the major number is increased
	   when there are significant jumps in functionality, the minor number
	   is incremented when only minor features or significant fixes have
	   been added, and the revision number is incremented when minor bugs
	   are fixed.
	   The @xv... batch files perform the following:
	   - change version number in Platform.pro
	   - add a description to the history file (for which you will be
	     prompted at the IDL prompt)
	   - adds new files and commits the changes with BaZaar
	6. Check the IDL log and respond appropriatly to the information given
	   by BaZaar. Check the section on BaZaar below for details. When using
	   a branch instead of a checkout, don't forget to push your changes. In
	   sourceforge.pro you find a procedure that allows you to do this,
	   amongst other bzr+SourceForge related operations (see BaZaar basics
	   below).

Release a new version of XRDUA:
	As for now, releases will be made by Wout De Nolf. This involves adding
	a release to the XRDUA homepage database and building/packing/uploading
	an XRDUA runtime version and code bundle to SourceForge and the XRDUA
	homepage.

Comments:
	Source files can also be manually downloaded off course (i.e. without
	making use of BaZaar and subscription to SourceForge) although it will
	be appriciated if you do. Setting up IDL is very similar, unpacking
	xrdua_src_vx-x-x-x.zip instead of branching with BaZaar. This is the
	latest "release" and might not contain some of the last revisions
	made by other developers.
	
	When you don't use the IDL workbench, make sure you have the XRDUA
	project directory and its subdirectories in the IDL "!path" list (e.g.
	!path+=';+C:\projects\idl\xrdua\xrdua').
	Use the command line versions for compiling (@compile), running (xrdua)
	and building (@build).


BaZaar basics:
--------------

	Make local branch from SourceForge:
	-----------------------------------
		bzr branch bzr+ssh://USERNAME@xrdua.bzr.sourceforge.net/bzrroot/xrdua/xrdua .../workspace/xrdua
	
	Push and pull new revisions to and from SourceForge:
	----------------------------------------------------
		cd, .../workspace/xrdua
		bzr push bzr+ssh://USERNAME@xrdua.bzr.sourceforge.net/bzrroot/xrdua/xrdua
		bzr pull bzr+ssh://USERNAME@xrdua.bzr.sourceforge.net/bzrroot/xrdua/xrdua
		
		remote: A --> B --> C --> D  (3 revisions were commited)
		         \                 \
		       (branch)           (pull)
		           \                  \
		local:      \--> A (no change) \--> D  (no revisions were commited)
		
		
		remote: A      (no change)       --> C   (no revisions were commited)
		         \                      /
		       (branch)             (push)
		           \                  /
		local:      \--> A --> B --> C   (2 revisions were commited)
	
	Merge diverged branches:
	------------------------
		cd, .../workspace/xrdua
		bzr merge bzr+ssh://USERNAME@xrdua.bzr.sourceforge.net/bzrroot/xrdua/xrdua
		(new revision created)
		bzr commit
		bzr push bzr+ssh://USERNAME@xrdua.bzr.sourceforge.net/bzrroot/xrdua/xrdua
		
		remote: A --> B --> C --> D   (3 revisions were commited)
		         \                 \  
		       (branch)           (merge) 
		           \                  \ 
		local:      \--> A --> X --> Y --> Z   (2 revisions were commited)
	
	Checkout (instead of branch):
	-----------------------------
		bzr checkout bzr+ssh://USERNAME@xrdua.bzr.sourceforge.net/bzrroot/xrdua/xrdua
		
		=> You don't have to explicitly push because "bzr commit" will do that automatically for a checkout.
		=> Merge divergence is done by "update":
			bzr update bzr+ssh://USERNAME@xrdua.bzr.sourceforge.net/bzrroot/xrdua/xrdua