This chapter of the Rose user guide attempts to introduce you to some fundamental aspects of Rose. We use a relatively detailed example, but don't worry too much about the details.
This guide assumes that Rose, cylc and FCM are already installed and configured correctly on your system.
You should also have looked at the Getting Started page.
Rose gives powerful command line utilities, and can be entirely used within a terminal and text editor. Rose also contains graphical user interfaces (GUIs) for optional use. We'll give a brief tour of the command line interface, and then discuss the GUIs.
This section takes us through the command line and text editor interface to Rose.
We'll begin by creating a suite for you to work with.
To create an empty new suite, issue the command:
rosie create
This command will prompt you to edit the suite discovery information file. Put some meaningful values in for the project (e.g. project=rose-user-guide) and the title settings (e.g. title=Brief tour). Save the file and exit the editor.
A new suite will have been created in the version control system, with a local copy created (i.e. checked out) at $HOME/roses/$ID/ where $ID is a unique ID for the new suite.
Change directory to the local copy of the suite and populate it by running the following commands:
cd $HOME/roses/$ID # replace $ID with your suite ID rose rug-brief-tour # Rose command to set up the tour suite
The rose rug-brief-tour command should create some content for this guide within the current working directory.
You will find the following files and sub-directories:
fcm_make: a special Rose
application to build an executable from a
source file containing a hello world
programfred_hello_world,
my_hello_mars,
my_hello_world: Rose
applications that invoke the
hello world executable using
different configurations.locate_fred: a preparation
task run each time before
fred_hello_world.This is a cycling suite that repeats
every 6 hours, with the first cycle starting at
20130101T0000Z (00:00, 1 January 2013)
and the last cycle starting 1 day later at
20130102T0000Z (00:00, 2 January
2013). Cycling suites typically need special start
tasks to boot up - in our case,
fcm_make is run at the beginning of
the suite, in the first cycle only.
fcm make using the configuration
in
app/fcm_make/file/fcm-make.cfg.At this point, you may want to have a look at the files before moving on to the next section. You may also want to commit your suite - if so, change directory to the working copy of your suite ($HOME/roses/$ID). To add new files for version control, run:
fcm add -c
To commit your changes, run:
fcm commit
Install and run the suite by using the following command:
cd $HOME/roses/$ID # replace $ID with your suite ID rose suite-run
This will install your suite under
$HOME/cylc-run/$ID/, start your suite
with cylc and fire up cylc gui
$ID.
Whilst the suite is running you can explore the
cylc gui. Try experimenting with
different viewing options using the toolbar.
The suite should run successfully to completion
and shutdown (the status bar should indicate
stopped with 'succeeded'). You can now
quit the cylc gui.
Note: If you quit cylc gui by
mistake, you can restart it by typing rose
suite-gcontrol --name=$ID on the command
line.
The output of your suite can be found at $HOME/cylc-run/$ID/.
The sub-directory log/ contains the log files produced by the suite. In particular, the log/job/ directory contains the STDOUT and STDERR from each task together with the script used to run the task.
You can type rose suite-log
--name=$ID to launch a web browser and view
the output of your suite via Rose Bush.
The share/ sub-directory is used by the tasks in the suite to share files over the lifetime of the suite. In this example suite, the build created by the fcm_make task can be found here.
The share/cycle/ sub-directory is to share files that are regularly generated, archived and removed by cycling tasks.
The work/ sub-directory contains the working directory for the tasks at their run times. It can be used by the tasks to create files that are only relevant to the tasks.
For help with Rose and Rosie commands, see the Command Reference.
This section explores working using the Rose system GUIs. You should complete the above command line tour before starting this one.
We'll use the discovery GUI to find and checkout our example suite. Open a Linux/Unix terminal and issue the command:
rosie go
You should see a list of your checked-out suites as rows in a table.
You could find other suites by using the toolbar search and searching for text strings, or using the advanced query panel (show it by clicking the rightmost toolbar button).
There are toolbar options to create and copy suites. Copying and other actions can be done by right clicking on a suite.
Look at the list to find the row that has the suite $ID, project, and title from the command line tour. If you double-click on it, your suite will be opened using the Rose configuration editor.
Go ahead and double click on your suite. The config editor GUI will now launch.
The config editor should have started up with a view of your suite.
You can see from the toolbar that you can perform actions like Undo, Redo and Find.
On the left hand side is a panel containing a tree with named nodes. If you expand these, you can see that this represents the suite and application configurations. Each section in a configuration is (normally) a node here. Navigate to the application section my_hello_saturn -> env and click on env.
A page should have launched in the right hand panel. This contains widgets for altering the env section of the application my_hello_saturn.
Try altering the value of some of the settings, either using the text box or the spin (numeric) buttons. When the settings are a different value to the saved ones, their names will change colour. You can Undo and Redo your actions. You can also Save your changes.
If you move the mouse over the setting names, you can see some descriptive text. You can access further help by clicking the little menu button next to the setting name and selecting Help or Web Help.
The config editor acts as a specialist text editor for Rose configuration files - pressing Save in the config editor is the same as pressing it in gvim or gedit.
Rose configuration files dumped through the
config editor, rose macro, or
rose config-dump will be
pretty-printed for consistency (so diffs are
possible), which may mean some extraneous
whitespace is removed and some sorting is performed
if anything is out of place.
You can commit your suite by launching a terminal then typing fcm commit in it, in the normal way. You can launch a terminal from inside the GUI with Ctrl-T or by using the menu: Tools -> Launch Terminal.
You can run your suite by clicking the Run
Suite button on the toolbar or selecting
Tools -> Run Suite -> Default from
the top menu. This will invoke rose
suite-run.
You have finished the brief tour. Why not try the Metadata Tutorial or read more about the GUIs at Config Editor Reference and Rosie Go Reference?