Skip to content

Latest commit

 

History

History
383 lines (241 loc) · 9.46 KB

Readme-PreinstalledVM.rst

File metadata and controls

383 lines (241 loc) · 9.46 KB
Raw

Preinstalled VMs

This document describes how to work with one of the preinstalled VMs.

In this document the example Project is called MyProject. Of course you can and should adapt this name to your needs.

Prerequisites

Please note that some knowledge is needed to be able to use rmtoo. These are:

  1. Basic Linux knowledge: Logging in a system, using a console / shell, executing a command, using make.
  2. Using a text editor: Any text editor is usable - preferred: emacs.
  3. Basic YAML or JSON knowledge: The configuration is using either format.

For the requirement management tool rmtoo itself:

  1. Concept of requirement and design decision.
  2. Concept of rmtoo.
  3. 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:

make

Check Artifacts

All artifacts are created in the sub-directory artifacts.

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

View Artifacts

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:

evince artifacts/requirements.pdf

For viewing the generated images:

eog artifacts/req-graph1.png

If you want to have a look at the generated html files, start

firefox

and browse to:

file:///home/<username>/MyProject/artifacts/html/ReqsDocument.html

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

emacs ~/.emacs

and add the line

(load-file "/usr/local/pkg/rmtoo/rmtoo/contrib/req-mode.el")

If your internet connection is not that fast, you can use the emacs directly in the console. To enable this, always use the -nw option to emacs, also e.g.:

emacs -nw ~/.emacs

Use Cases

Add a Requirement

Adding a requirement consists of two steps:

  1. Create new requirement.
  2. 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:

emacs requirements/req2.req

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 the new req2 is a detail or breakdown of req1.

To add this relation, edit the existing req1

emacs requirements/req1.req

and add the line

Solved by: req2

To recreate the complete set of artifacts with the new requirement included, call

make

You can have a look at the changes as described in the previous section View Artifacts.

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:

emacs topics/NewTopic.tic

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

emacs topics/WhatsAbout.tic

And add a line like:

SubTopic: NewTopic

The last step is to move the requirement to the topic. Edit the requirement:

emacs requirements/req2.req

And change the Topic: to:

Topic: NewTopic

To update all the artifacts based on the new data set, call

make

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

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

man rmtoo

This page lists all the available man pages. To read one of them, e.g. the page that describes the analytics, use

man rmtoo-analytics

Next Steps

There are two additional example projects availble:

EMail client

A small project with eight requirements. This can be found in

https://github.com/florath/rmtoo/tree/master/doc/examples/EMailClient

rmtoo

Of course the requirements for rmtoo itself are written in rmtoo. Currently it contains about 200 requirements - including mostly all different types of outputs.

https://github.com/florath/rmtoo/tree/master/doc

In this directory, you can find the requirements, topics and so on.

FAQ

Some frequently asked questions with answers:

/usr/local/pkg/rmtoo/rmtoo/doc/other/FAQ.txt

Issues and Problems

If you run into issues or problems, you can report them on

https://github.com/florath/rmtoo/issues

Commercial Support

If you need extensions or consulting setting up or using rmtoo, please contact: [email protected]