Configuration Metadata is used to provide information about settings in Rose configurations. It is intended to:
For reference and a fuller picture of Rose configuration metadata, please refer to the Rose Reference Guide: Configuration Metadata.
This example uses the Rose example suite from the brief tour and assumes that you are familiar with it and have it to hand. Otherwise, go back to the brief tour and follow the instructions to check it out or recreate it.
We are going to develop metadata for the app
my_hello_mars. Change directory to the
suite directory, then change directory to
app/my_hello_mars/.
Open the Rose application file
(rose-app.conf) in this directory. It
should look like this:
[command] default=hello.exe [env] LANG_JUPITER=Europan MAX_TARGETS=5 WORLD=Mars
This configuration will run hello.exe with some environment variables set up - MAX_TARGETS, LANG_JUPITER, and WORLD.
We can compare the text in the
rose-app.conf with the display in the
Rose config editor.
Open this application directory in the Rose config editor by typing:
rose edit
Look at the page env. The three
options LANG_JUPITER,
MAX_TARGETS, WORLD appear in
raw form - there are no special widgets for the
number in MAX_TARGETS and no hover-over
descriptions of the variables or help. We actually
haven't added any value over the raw text. Let's
close the config editor for now.
Let's create a metadata directory and start adding some information.
If we were in a hurry, we could use the rose
metadata-gen command which will populate a
metadata configuration based on an application or
suite configuration. It can make educated guesses
about variable types as well (option
--auto-type). This provides a base for
further development, and saves a lot of typing.
We'll ignore it for the purposes of this guide.
Create the sub directory meta/ in
your application directory (inside
app/my_hello_mars/):
mkdir meta
This is where Rose will look for our metadata by default. We'll add a metadata file by running:
touch meta/rose-meta.conf
This is where the main metadata configuration lives. Open the file in a text editor.
Let's provide some type information about
MAX_TARGETS, an environment variable
from our rose-app.conf. This is read
in as an integer by our hello.exe
program.
The id for this variable is env=MAX_TARGETS, so add a section into the file:
[env=MAX_TARGETS]
We can specify that it's an integer by giving it a type:
[env=MAX_TARGETS] type=integer
We could also improve the way it's displayed by giving it a title:
[env=MAX_TARGETS] title=Max target number type=integer
Now if we save the file and open the application in the config editor again, we see that the value of MAX_TARGETS now appears in a special numeric widget, and that the title has replaced the name. You can see the difference easily by switching off the metadata via the menu option Metadata -> Switch Off Metadata. Remember to switch the metadata back on for the next part!
Setting the type does more than change the widget - it also instructs Rose to check that the input is valid for that type. If the value of MAX_TARGETS was 5.6 or banana, (anything non-integer) an error would be flagged.
You can view the data and metadata for MAX_TARGETS by clicking the small menu button next to the title and selecting Info.
We've set the type of MAX_TARGETS to integer, but we haven't ruled out choices of integer that would crash our code, such as negative integers. We need to restrict the number using a range. To do this, add a range as follows:
[env=MAX_TARGETS] range=0: title=Max target number type=integer
This means that any integer less than zero will be flagged as a problem.
Reload the metadata (toggle menu Metadata -> Refresh Metadata).
Now try decreasing the value of MAX_TARGETS below 0. An error will be flagged next to the variable and on the page list in the left hand panel. If you change it to an integer value of 0 or greater, the error will go away.
You can check syntax errors in the metadata that
you write using Rose's built-in metadata checker.
This is automatically run when the config editor
loads, but can also be run from the command line in
a metadata directory using rose
metadata-check.
Let's write some deliberately invalid metadata. Change the env=MAX_TARGETS section to read:
[env=MAX_TARGETS] range=0:not sure title=Max target number type=integer
If you reload the metadata, a dialog will appear warning you about a problem that's been detected. You can get more information by clicking the Information button in the dialog.
If you look at the variable in the config editor, the invalid range setting will have been switched off - if you open the MAX_TARGETS Info dialog again (using the small menu button next to the title on the env page) it won't appear as part of the metadata.
Change the metadata back to a valid state by removing the not sure text in the range entry.
Your range metadata should now work OK again.
Let's now make the WORLD setting less ambiguous. Create a section in the metadata
[env=WORLD]
Add a title and description:
[env=WORLD] description=Choose your target world to say hello to. title=World
If you reload the metadata you'll see that WORLD now has some helpful hover-over text when you move the mouse over the title.
Depending on your view options (Metadata -> Layout Preferences menu) you may see it as smaller-font text below the title.
We'll decide to be harsh about grammar and insist that the first letter of WORLD must be capitalised. To do this, we can use a very simple regular expression by adding a pattern:
[env=WORLD] description=Choose your target world to say hello to. pattern=^[A-Z] title=World
Reload the metadata and change the first letter of the value of WORLD to lowercase.
You've now caused an error! The menu button next to the World label will change colour and have hover-over text describing the error. There should be some error icons in the page list as well.
You can change the value back to fix it (try using Undo or Ctrl-Z in the config editor).
Alternatively, we could just give a list of valid world names - this means we won't need a regular expression or any other type information. Let's remove the pattern and add a list of values:
[env=WORLD] description=Choose your target world to say hello to. title=World values=Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, Neptune
(You may add or remove Pluto in line with your personal preferences.)
Reload the metadata and you now get a drop-down list of worlds to choose from. Isn't that nice! Rose will now check WORLD in the future to make sure its value is in this list.
Set the WORLD value to Jupiter using the drop-down list.
Looking at the other variables, it doesn't appear as if we really need a Jupiter language LANG_JUPITER set when WORLD is not Jupiter. Let's add a trigger to automatically handle this:
[env=WORLD] description=Choose your target world to say hello to. title=World trigger=env=LANG_JUPITER: Jupiter; values=Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, Neptune [env=LANG_JUPITER]
We also need a env=LANG_JUPITER section, as we're referencing it in a trigger.
This means that LANG_JUPITER will be
ignored when WORLD is not
Jupiter - but it will be
enabled when it is. Ignored variables
won't get passed into our hello.exe
application.
Reload the metadata. Now when you change the value of WORLD to Saturn, or any other planet, LANG_JUPITER will be ignored and hidden by default in the config editor (you can show it by selecting View -> View All Ignored Variables). If you change it back to Jupiter, it will be enabled and re-appear.
When you're done, change WORLD to Earth and save.
An important advantage of adding metadata is that it acts as a memory of inputs. If you remove WORLD (in a text editor or using the little button next to the title in the config editor) and then save, any information about the variable WORLD is lost from your physical copy of the application. Close the config editor and check the application file.
If you then re-open the WORLD-less
application in the config editor, you can navigate
to the env page and see that it's
missing.
If you select the menu option View -> View Latent Variables, any variables that are in the metadata but aren't in the application will be displayed - WORLD will reappear as a ghost! You can add the variable back into the application by clicking on the button next to the name and selecting Add.
Let's add some proper help for LANG_JUPITER - Jovian linguistics are notoriously difficult. Add:
[env=LANG_JUPITER]
help=This variable controls which language to use when saying hello
=to Jupiter.
=
=The Galilean moons of Jupiter are Io, Europa, Ganymede and Callisto.
=
=The Great Red Spot people are not worth it.
If you reload the metadata you can now click on the title of LANG_JUPITER or use the menu button to launch a help dialog.
Let's improve the look of the page
by adding metadata for the section:
[env]
description=Hello Environment
help=These environment variables provide overrides for the hello.f90 program.
=
=Use these to say hello to other planets.
title=Environment
Reload the metadata and you should then have a modifed page name, hover-over text (description) when the mouse is over the page name, and a menu option for help for this section (right click on the page name).
You should also see the description text at the top of the page.
We can also swap variables in and out of pages,
regardless of whether they belong in the
env application section or not. Let's
move LANG_JUPITER. Add a namespace
(ns):
[env=LANG_JUPITER]
help=This variable controls which language to use when saying hello
=to Jupiter.
=
=The Galilean moons of Jupiter are Io, Europa, Ganymede and Callisto.
=
=The Great Red Spot people are not worth it.
ns=languages
A reload of the config editor will show that LANG_JUPITER has been moved to a different page called languages. This can be useful for moving environment variables to their relevant namelists, or breaking up large namelists into several sections.
Sometimes just having help or descriptions isn't enough, or there's a more relevant resource page on the Web - in this case you can add Web Help using a url:
[env=LANG_JUPITER]
help=This variable controls which language to use when saying hello
=to Jupiter.
=
=The Galilean moons of Jupiter are Io, Europa, Ganymede and Callisto.
=
=The Great Red Spot people are not worth it.
ns=languages
url=http://solarsystem.nasa.gov/planets/profile.cfm?Object=Jupiter
Navigate to the page containing LANG_JUPITER. After a reload of the metadata, click the menu button next to the LANG_JUPITER name to launch a menu - this will now contain a Web Help item.
If there isn't any help defined for a variable, clicking the name will launch the web help url instead.
You can also do this in another way. Variable ids or "http://"-prefixed URLs in the help will be clickable - this will either navigate to the variable or launch a web page.
Add some help for the env=WORLD option:
[env=WORLD]
description=Choose your target world to say hello to.
help=Select a target world.
=
=This should be one of the formally recognised Solar System planets.
=It would be nice to be able to say hello to some of these:
=http://phl.upr.edu/library/notes/astellarsystemmapforexoplanets
=but we're not there yet.
=
=This variable gets passed to command=default.
title=World
trigger=env=LANG_JUPITER: Jupiter;
values=Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, Neptune
The web URL and the variable id should be clickable when you reload the metadata and launch the help.
You could also make use of the same functionality in the description text for sections or namespaces - the text at the top of the page.
We've finished! However, there are other things you can do with configuration metadata. Make sure you have a good idea of when to use these by consulting the Configuration Metadata Reference.
You could also look at the Advanced Metadata Tutorials.