All the dashboard libraries are kept under the CERN Central SVN Repository. You can check the dashboard svn web frontend here.
This section will cover the way the dashboard packages are organized and how you can check them out from the svn service and build them in your own system.
The different packages of the dashboard (mapping to the different components described in the other sections of this document) are usually placed in distinct modules.
As an example, for the command line tools there is a arda.dashboard.cli which contains the common cli class definitions, and an additional module for each cli area. That is arda.dashboard.cli-data for the data management CLIs, arda.dashboard.cli-job for the job monitoring CLIs, and an additional one for other dashboard applications.
In the same way, the arda.dashboard.web contains the common web application framework classes, arda.dashboard.web-data contains the data management web application, and arda.dashboard.web-job the job monitoring web application. There are others for the additional applications developed on top of the dashboard web framework.
This component split aims to having each component versioned, managed and released independently. If you follow the suggestion above, you will be able to release a patch with a bug fix on the cli without having to release the web application package. But if you think you don't need this (although in the future you'll find out you actually did), you may have in the same svn module the sources for both a web application and a set of command line tools.
Additionally there is a top level module named arda.dashboard where all the build related information is kept, as well as other generic files - like the common docbook template definitions. You only need to update this module when you need to update the version of one of your components after a release.
![[Note]](../../../common/html/images/note.png) | Note |
|---|---|
In the future there will be a tool to manage the different release branches, so this manual update of the release files will not be necessary and the arda.dashboard module will never need to be touched. |
Having modules split in this way means that there will be dependencies among them. All application specific CLI modules require the common arda.dashboard.cli. In the same way, to be able to use the dashboard build you need the dashboard distutils extensions, which come with the arda.dashboard module. For all similar cases, you need to make sure that you first checkout and stage all the dependencies (staging is described in detail in Section 2.3, “Build Commands”).
The dashboard SVN modules follow a common internal structure, so that the different deliverables (libraries, documentation, binaries, ...) can be built and packaged in an unique and straigthforward way. The relevant files and directories are shown below.
| File / Directory | Description |
|---|---|
| setup.py | Main distutils setup file (packages to include, ...) |
| setup.cfg | Distutils configuration (default parameters for the different distutils commands) |
| module.cfg | Module properties. This is a way to store in an external file the information that is usually passed directly to the distutils setup method. Only used if the the dashboard specific setup method is invoked, instead of the default distutils setup. This custom setup is simply loading properties from this file and then invoking the default setup |
| MANIFEST.in | Additional files (not libraries) to include in the package (RPM, tarballs, ...) |
| LICENSE | The license of this package |
| README | Contains some details about the packages (might include links to the manual, or just contain the manual inside of it - if the default docbook documentation is not being used) |
| RELEASE-NOTES | Keeps track of the package evolution. On every release (major, minor, patch or candidate) a new entry is added describing the changes (Section 3, “Software Releases” provides all details about package releases) |
| ./config (dir) | Package configuration files. Usually each module will have additional configuration files stored in this area, but at least one directory following the package name should exist. In the arda.dashboard.web example, a ./config/web directory with a module configuration file dashboard-web.cfg is expected to exist. Details on this configuration file are presented in Section 4, “Configuration” |
| ./doc (dir) | Holds the package documentation. This includes different sub-directories, namely: guides, for user guides like this one; man, for command line tool man pages |
| ./lib (dir) | All the package libraries should go in here. It is recommended that a 'dot' separation is used for the different packages, but it is not at all a requirement |
| ./templates (dir) | Optional directory holding the web application static files (web pages, xsl stylesheets, images, ...) |
| ./build (dir) | Temporary directory created for build files. It does not go in CVS |
Looking at any of the existing module's file/directory contents should be enough to understand what should be put in. As it is quite simple, the arda.dashboard.demo module is a good starting point. Of special interest is the module.cfg file, which is an extension to distutils containing all the module's details.
Also important is the setup.cfg, especially the configuration for the bdist_rpm command, as this is where the package dependencies are defined. Below is an example of the dependencies for the web application package.
[bdist_rpm]
...
requires = libxslt-python >= 1.1.11
httpd >= 2.0
mod_python >= 3.1.3
dashboard-common >= 0.1.0a6
dashboard-dao >= 0.1.0a18
The dashboard build uses the standard python distutils libraries, extending them whenever necessary, as listed below.
rocha@pcitgm10:~/workspace/dashboard-head/arda.dashboard$ python setup.py --help-commands
Standard commands:
...
Extra commands:
doc generate the documentation (source code, docbook guides, man pages, ...)
release release the module (updating version and release notes, tagging in cvs)
test run all or part of the module unit tests
fullbuild performs a full dashboard build (you should not care about it)
stage put module data files and libraries in the stage directory
You can check the details of each of these extra commands by issuing
python setup.py <command-name> --help
As an example is always better than a thousand words, check below for how to build the dashboard from scratch.
Example 1. Build Example
rocha@pcitgm10:~$ cd workspace/
rocha@pcitgm10:~/workspace$ mkdir dashboard-head
rocha@pcitgm10:~/workspace$ cd dashboard-head/
rocha@pcitgm10:~/workspace/dashboard-head$ svn co http://svnweb.cern.ch/guest/dashboard/trunk/arda.dashboard http://svnweb.cern.ch/guest/dashboard/trunk/arda.dashboard.common
A arda.dashboard/LICENSE
A arda.dashboard/module.cfg
A arda.dashboard/config
...
Checked out revision 15081.
rocha@pcitgm10:~/workspace/dashboard-head$ cd arda.dashboard
rocha@pcitgm10:~/workspace/dashboard-head/arda.dashboard$ python setup.py stage
rocha@pcitgm10:~/workspace/dashboard-head/arda.dashboard$ cd ../arda.dashboard.common/
rocha@pcitgm10:~/workspace/dashboard-head/arda.dashboard.web$ python setup.py stage
The example above would stage the arda.dashboard.common module, meaning it would make a local installation of this module (using the stage directory as the root). Section 9, “Installing a developer environment” provides more details on how to build your own local workspace.