This document describes how to work with one of the preinstalled VMs.
In this document the example Project is called
course you can and should adapt this name to your needs.
Please note that some knowledge is needed to be able to use rmtoo. These are:
- Basic Linux knowledge:
Logging in a system, using a console / shell, executing a command,
- Using a text editor: Any text editor is usable - preferred: emacs.
- Basic YAML or JSON knowledge: The configuration is using either format.
For the requirement management tool
- Concept of requirement and design decision.
- Concept of rmtoo.
- Concept of a directed graph (digraph).
If not already done, now is the time to step through the rmtoo presentations which can be found on http://rmtoo.florath.net.
This document is not an introduction to Linux; this document is not an introduction to rmtoo.
Starting Preinstalled VMs
For different usage scenarios there are different VM flavors. There is a dedicated document where the flavors are described.
To use the preinstalled VMs you need access to AWS EC2. Please consult the Readme for hints and tips.
No automated Backup
There is no backup done of any data. If you start your own project you need to create backups by yourself.
Copy the Template Project
Copy the template project to the home directory and change the working directory to the new project.
cp -r /usr/local/pkg/rmtoo/rmtoo/contrib/template_project MyProject cd MyProject
This is a minimalist project with only two requirements - but the whole environment and infrastructure is set up so that is easy to extend this.
Create All Artifacts
To create all artifacts for the project, type:
All artifacts are created in the sub-directory
ls -l artifacts
A possible result looks like:
drwxr-xr-x 2 rmtoo rmtoo 4096 May 9 08:33 html -rw-r--r-- 1 rmtoo rmtoo 268 May 9 08:33 req-graph1.dot -rw-r--r-- 1 rmtoo rmtoo 13027 May 9 08:33 req-graph1.png -rw-r--r-- 1 rmtoo rmtoo 333 May 9 08:33 req-graph2.dot -rw-r--r-- 1 rmtoo rmtoo 16375 May 9 08:33 req-graph2.png -rw-r--r-- 1 rmtoo rmtoo 1369 May 9 08:33 reqsprios.tex -rw-r--r-- 1 rmtoo rmtoo 30 May 9 08:33 reqs-version.txt -rw-r--r-- 1 rmtoo rmtoo 1224 May 9 08:33 reqtopics.tex -rw-r--r-- 1 rmtoo rmtoo 3390 May 9 08:33 requirements.aux -rw-r--r-- 1 rmtoo rmtoo 17073 May 9 08:33 requirements.log -rw-r--r-- 1 rmtoo rmtoo 885 May 9 08:33 requirements.out -rw-r--r-- 1 rmtoo rmtoo 106423 May 9 08:33 requirements.pdf -rw-r--r-- 1 rmtoo rmtoo 1098 May 9 08:33 requirements.toc -rw-r--r-- 1 rmtoo rmtoo 41819 May 9 08:33 stats_burndown.csv -rw-r--r-- 1 rmtoo rmtoo 0 May 9 08:33 stats_burndown.csv.est -rw-r--r-- 1 rmtoo rmtoo 72883 May 9 08:33 stats_burndown.eps -rw-r--r-- 1 rmtoo rmtoo 7677 May 9 08:33 stats_burndown.pdf -rw-r--r-- 1 rmtoo rmtoo 22 May 9 08:33 stats_reqs_cnt.csv -rw-r--r-- 1 rmtoo rmtoo 18187 May 9 08:33 stats_reqs_cnt.eps -rw-r--r-- 1 rmtoo rmtoo 6963 May 9 08:33 stats_reqs_cnt.pdf -rw-r--r-- 1 rmtoo rmtoo 41819 May 9 08:33 stats_sprint_burndown.csv -rw-r--r-- 1 rmtoo rmtoo 0 May 9 08:33 stats_sprint_burndown.csv.est -rw-r--r-- 1 rmtoo rmtoo 72904 May 9 08:33 stats_sprint_burndown.eps -rw-r--r-- 1 rmtoo rmtoo 7909 May 9 08:33 stats_sprint_burndown.pdf
For a complete description of all artifacts consult the rmtoo presentations or man pages (as described later in this document).
There are two ways to view the generated artifacts: using local installed tools or transfer the files to your local computer and view them there.
View Artifacts using Tools installed on the VM
As a precondition you need a local X-Server and you need to connect to
the VM using
ssh -X. In this case you can open the files with the
pre-installed tools on the VM. Example: to open a PDF file use:
For viewing the generated images:
If you want to have a look at the generated html files, start
and browse to:
The username is the default username of the VM. Depending on the flavor, distribution and boot configurations that might differ.
View Artifacts using local Tools
Another possibility is to transfer the data to your local computer using the ssh or sftp protocol. For every (local) operating system there exist many different tools. Please consult the internet.
Optional: Configuring Emacs
When using emacs it is very convinient to enable syntax highlighting. To enable this, run
and add the line
If your internet connection is not that fast, you can use the emacs
directly in the console. To enable this, always use the
option to emacs, also e.g.:
emacs -nw ~/.emacs
Add a Requirement
Adding a requirement consists of two steps:
- Create new requirement.
- Create dependency from existing to new requirement.
The easiest way to create a new requirement is to create a copy of an existing:
cp requirements/req1.req requirements/req2.req
Then change the new requirement with the text editor:
You must change the name (this must be unique). A good practice is to use the same name for the requirement as for the file. You might also want to change other values as well.
As a second step you have to create the link between the existing
requirements and the new requirement. In this example we assume that
req2 is a detail or breakdown of
To add this relation, edit the existing
and add the line
Solved by: req2
To recreate the complete set of artifacts with the new requirement included, call
You can have a look at the changes as described in the previous
Add a Topic
A topic is a way of clustering requirements; depending on the output they appear as different chapters, sections or pages.
Topic can have sub-topics; sub-topic can have sub-sub-topics and so on.
To create a new topic, the easiest way is to copy an existing one:
cp topics/WhatsAbout.tic topics/NewTopic.tic
As for the requirement, change the content of the new topic:
Especially change the name. Also here it is best practice to use the same (or a similar) name as for the filename.
The next step is to include the new topic into the topic hierarchy.
For example we will add here the
NewTopic as a subtopic of the
WhatsAbout. Therefore edit the existing topic
And add a line like:
The last step is to move the requirement to the topic. Edit the requirement:
And change the
To update all the artifacts based on the new data set, call
In rare cases - depending on how you change the files and how the VM
is time synchronized - when adding new elements, the call to make will
do nothing (Message: make: Nothing to be done for 'all'.). To get
around this, remove the Makefile dependencies and run
rm -f .rmtoo_dependencies make
Using man Pages
The complete documentation of rmtoo can be read as man pages. There are about 30 man pages - each describing a different aspect of rmtoo.
To get an overview over the available man pages, use
This page lists all the available man pages. To read one of them, e.g. the page that describes the analytics, use
There are two additional example projects availble:
A small project with eight requirements. This can be found in
Of course the requirements for rmtoo itself are written in rmtoo. Currently it contains about 200 requirements - including mostly all different types of outputs.
In this directory, you can find the
Some frequently asked questions with answers:
Issues and Problems
If you run into issues or problems, you can report them on
If you need extensions or consulting setting up or using rmtoo, please contact: firstname.lastname@example.org