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 with 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), or from within
	   the IDL workbench "File > Switch Workspace > Other..."
	2. Make a project subdirectory by branching it from the SourceForge branch:
	   bzr branch bzr+ssh://USERNAME@xrdua.bzr.sourceforge.net/bzrroot/xrdua/xrdua .../workspace/xrdua
	3. 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)
	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 commandline

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 (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 (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).

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 to SourceForge.

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.
	
	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