NRAO Home  >  Green Bank  |  Wiki Topic:    GB > Software > MnCKnowledge > DevelopingMC

Changes | Index | Contents | Search | Statistics | Go

Developing M&C Software

• Intro
• Setting up your sandbox
  • Checkout Source
  • Set-up your build environment
  • Build the new source tree
  • Inspect the output of the builds
• Unit Tests
  • Ygor
  • Gb
  • Gbt
• Installation and Using the Simulator
  • Installation
    • Setup up the installation environment
    • Create the installation directories
    • Install
    • Run setFileModes script
  • Running against the simulator

Intro

For a developer unfamiliar with the M&C software, what are the methods and best practices involved with this code tree. Here is a brief explanation of how to setup one's sandbox, run unit tests, and run with the simulator. This is not a tutorial on more basic concepts, like using CVS.

Setting up your sandbox

Development should take place in the developer's /home/sandboxes/developer area. The process for checking out, and building the M&C source code can be adapted from the steps included in CreatingNewMCVersion. Here is that adaptation, but reader be warned, the below will probably not be kept up to date as well as the former link!

Checkout Source

For checking out the trunk:

$ cd /home/sandboxes/developer
$ mkdir mc
$ cd mc
$ for d in ygor gb gbt
> do
> cvs checkout $d
> done
$ 

Set-up your build environment

$ export YGOR_ROOT=/home/sandboxes/developer/mc/ygor
$ export GB_ROOT=/home/sandboxes/developer/mc/gb
$ source $YGOR_ROOT/ygor.bash

Build the new source tree

IMPORTANT: You may execute all the steps, save the last one, with your login. To successfully execute the mkTelescopeDirs script, you must be logged in as monctrl.

$ cd /home/sandboxes/developer/mc
$ for d in ygor gb gbt
> do
> cd $d
> touch .depend
> make 
> make depend
> cd ..
> done
$ cd /home/sandboxes/developer/mc/ygor/utilities/host/installScripts
$ su monctrl
$ ./mkTelescopeDirs

Inspect the output of the builds

Inspect the output of the builds to guarantee the release is clean and complete. Errors must be resolved before continuing. Warnings should be forwarded to the responsible programmer.

TIP: In order to guarantee that there are no errors or warnings during any of the steps in the build and install process you would have to either stare at the output during the entire procedure, or pipe stdout & stderr to a file and look for errors there. When piping, however, the output disappears from your shell and you can't see what is going on. You can have it both ways by combining stdout and stderr and using the 'tee' utility:

> make 2>&1 | tee make.out

Unit Tests

Unit Tests are run from the source directories.

Running the unit tests for the M&C modules requires some preparation. This is due to the fact that some of the unit tests need a) a configuration file, or b) to run against a daemon. For this reason, the unit tests need to run against a simulation. Because of the dependencies of some unit tests on M&C simulator components, the developer should pay special attention to whether or not the simulator is in use by checking the simulator calendar prior to running unit tests. If it is in use, results of the unit tests may not be consistent or reliable. Thus in the below instructions (from the comments in the gbt_unit_test script), the /home/sim/gbt.bash and sparrow.bash files are sourced:

1. Define YGOR_ROOT, e.g., export YGOR_ROOT=/home/sandboxes/developer/mc/ygor
2. Define GB_ROOT, e.g., export YGOR_ROOT=/home/sandboxes/developer/mc/gb
3. source $YGOR_ROOT/ygor.bash
4. source /home/sim/gbt.bash
5. Select a sparrow, e.g., source /home/sparrow/integration/sparrow.bash

Then run the tests:

Ygor

$ cd /home/sandboxes/developer/mc/ygor/unit_test
$ ./ygor_unit_test

Sib: ..


OK (2 tests)


Control: ......


OK (6 tests)


TimeStamp: ...............


OK (15 tests)


IF: ...................................


OK (35 tests)


Util: ......


OK (6 tests)


ScanSpec: ......


OK (6 tests)


DatabaseAccess: .


OK (1 tests)


ScanCoordinator: .


OK (1 tests)

Gb

Running the unit tests for the gb module is even easier: there are none.

Gbt

$ cd /home/sandboxes/developer/mc/gbt/unit_test
$ ./gbt_unit_test

Installation and Using the Simulator

Before a developer can run the code they are developing in the simulator, they must install it.

Installation

The key to understanding the installation is that everything is installed except the config files. As an example, if one inspects the /home/gbt directory, one can see that most directories are symbolic links, except for the etc directory (home of etc/config):

[pmargani@nereid /home/gbt]$ ls -lrt
drwxrwxr-x  8 monctrl  monctrl  4096 May  8  2006 etc
lrwxrwxrwx  1 monctrl  monctrl    25 Mar 28 13:28 tcl -> /home/gbtversions/7.2/tcl
lrwxrwxrwx  1 monctrl  monctrl    25 Mar 28 13:28 lib -> /home/gbtversions/7.2/lib
lrwxrwxrwx  1 monctrl  monctrl    27 Mar 28 13:28 glish -> /home/gbtversions/7.2/glish
lrwxrwxrwx  1 monctrl  monctrl    26 Mar 28 13:28 exec -> /home/gbtversions/7.2/exec
lrwxrwxrwx  1 monctrl  monctrl    25 Mar 28 13:28 bin -> /home/gbtversions/7.2/bin
lrwxrwxrwx  1 monctrl  monctrl    26 Mar 28 13:28 apps -> /home/gbtversions/7.2/apps
lrwxrwxrwx  1 monctrl  monctrl    17 Jul 18 11:23 sparrow -> /home/sparrow/7.2
...

This is partially due to the fact that the configuration files in etc/config are not entirely under developer's control - they are being continually editied by astronomers and engineers. Consequently, they aren't under CVS control either. The revision control for these files is adhoc.

For the simulator, the configuration files in /home/sim/etc/config have all been tailored to meet the needs of the M&C simulation (i.e., don't connect to the real telescope).

Consequently, for installing the developer's sandbox, one method is to simply install in one's own test installation in /home/simversions. This will help the developer when switching the simulator to their installation.

Here are the simple instructions for installing, again adapted from CreatingNewMCVersion.

Setup up the installation environment

$ export YGOR_ROOT=/home/sandboxes/developer/mc/ygor
$ export GB_ROOT=/home/sandboxes/developer/mc/gb
$ export YGOR_INSTALL=/home/simversions/developer
$ source $YGOR_ROOT/ygor.bash

Create the installation directories

$ su monctrl
$ cd /home/simversions
$ mkdir developer
$ cd /home/sandboxes/developer/mc/ygor/utilities/host/installScripts
$ ./mkTelescopeDirs

Install

$ cd /home/sandboxes/developer/mc
$ for d in ygor gb gbt
> do
> cd $d
> make install
> cd ..
> done
$

Run setFileModes script

There are a few executables which must be setuid and owned by root. The setFileModes script run on gbtdata as root will set the proper modes and ownership and display a list of the files so changed. A successful run produces output similar to the following (files shown here may differ from the output of the current version of the script).

$ ssh colossus
$ cd /home/sim
$ sudo /home/sim/setFileModes /home/simversions/developer
-rwsr-xr-x   1 root     monctrl  8690247 Sep 19 10:28 /home/simversions/developer/exec/sparc-solaris/antennaMgr.muacu
-rwsr-xr-x   1 root     monctrl  8690247 Sep 19 10:28 /home/simversions/developer/exec/sparc-solaris/antennaMgr.virgo
-rwsr-xr-x   1 root     monctrl  9564815 Sep 19 10:28 /home/simversions/developer/exec/i386-linux/antennaMgr.prima
-rwsr-xr-x   1 root     monctrl  9564815 Sep 19 10:28 /home/simversions/developer/exec/i386-linux/antennaMgr.virgo
-rwsrwxr-x   1 root     monctrl  1274684 Sep 19 10:15 /home/simversions/developer/exec/sparc-solaris/dataCollect
-rwsrwxr-x   1 root     monctrl   167056 Sep 19 10:17 /home/simversions/developer/bin/i386-linux/get_spigot_data
-rwsrwxr-x   1 root     monctrl   196059 Sep 19 10:17 /home/simversions/developer/bin/i386-linux/spigot_takedata
Done.
$

Running against the simulator

A full explanation, along with rules for running the simulator, are provided at RunningTheSimulator.

It is recommended that you read the full explanation, but here's the basic idea:

To switch simulation versions, one can follow the same steps spelled out in SwitchingMCVersions, except all references to /home/gbt should be replaced with /home/sim. In addition, the RunningTheSimulator wiki points out that one can configure which sparrow to run in the simulator manually as well.

Another confusing issue that isn't mentioned explicitly, is that the Antenna simulator is sometimes used for tests along with the production system. This happens for instance, on maintenance days. Thus the simulation calendar is important.

This section could use some more work I think.

-- PaulMarganian - 19 Jul 2007