systress Files

           ============================================
                            System stress
                              (SYSTRESS)
           ============================================





CONTENTS OF THIS FILE
=====================
   
 * Introduction
 * Maintainers
 * Build suites
 * Download
 * Autotools mode
   * Configuration
   * Build, installation
   * Tests
   * Tests coverage measurement
 * cmake mode
   * systress_install.sh script
   * Build, installation, cleanup
   * Tests
   * Tests coverage measurement
   * Packaging
   * Notes about RPM package
   * Notes about DEB package
 * Documentation
   * On line manuals
   * Articles
 * References


Introduction
============

SYSTRESS is a tool in charge of loading and evaluating the latency of a Linux
system. It is a spin-off of the famous cyclictest tool.

SYSTRESS is distributed under the GNU GPL license.

The current document concerns the 0.3.0 version of the SYSTRESS package.


For a full description of the software, visit the project page:

https://sourceforge.net/projects/systress/



Maintainers
===========

To report a bug or design enhancement, please contact:

  Rachid Koucha <rachid dot koucha at gmail dot com>


Build suites
============

SYSTRESS comes with two build flavors : AUTOTOOLS and CMAKE.
We tried to provide the same features in both frameworks but it is not so
obvious. For examples, DEB and RPM packages generation are provided only
in cmake mode.

Currently, only the CMAKE mode is available. The tool is under active
development to provide the AUTOTOOLS version very soon.

Download
========

* The source tree of this package can be downloaded from:

  https://sourceforge.net/projects/systress/


===============================================================================
                                      AUTOTOOLS MODE
===============================================================================


Will be available in a subsequent version...



===============================================================================
                                      CMAKE MODE
===============================================================================

systress_install.sh script
==========================

This script is a swiss army knife to make several things:

$ ./systress_install.sh -h

Usage:

  systress_install.sh [-b browser] [-c] [-T|-C] [-d install_dir]
                      [-B] [-I] [-U] [-A] [-P RPM|DEB|TGZ|STGZ] [-h]

    -b    : Browser's pathname to display the test coverage HTML results
    -c (*): Cleanup built objects
    -C    : Launch the test coverage measurement
    -T    : Launch the regression tests
    -d    : Installation directory (default: /usr/local)
    -P (*): Generate DEB/RPM/TGZ/STGZ packages
    -B    : Build the software
    -I (*): Install the software
    -U (*): Uninstall the software
    -A    : Generate an archive of the software (sources)
    -h    : this help

   (*) Super user rights required


Note that some options require super user priviledges to run. Use "sudo" for
example.


Build, installation, cleanup
============================

* For a complete installation in the default /usr/local subtree:

$ sudo ./systress_install.sh -I

* To uninstall the software:

$ sudo ./systress_install.sh -U

* To cleanup every generated files to go back to original source tree:

$ sudo ./systress_install.sh -c


Tests
=====

The regression tests are based on CHECK library. The latter must be installed
prior to launch the tests.


. To trigger the regression tests for the whole software:

$ ./systress_install.sh -T
100%: Checks: 47, Failures: 0, Errors: 0


Tests coverage measurement
==========================

. To trigger test coverage measurement for SYSTRESS (with a display of the
result in firefox):

$ ./systress_install.sh -C -b firefox

Note: As the software is not completely mature, the test suite does not cover
      the whole software but it will be enhanced very soon


Packaging
=========

. To make a source package, use the -A option of systress_install.sh:

$ ./systress_install.sh -A

This makes a TGZ file of the complete source tree: systress_src-0.3.0.tgz


. In cmake mode, we provide the ability to generate Debian (DEB), Red-Hat
  Package Manager (RPM), Tar GZipped (TGZ) and Self Extracting Tar GZipped
  (STGZ) binary packages.

. To build the packages (TGZ, DEB, RPM...):

$ sudo ./systress_install.sh -c -P tgz -P rpm -P deb -P stgz

This makes the following binary packages:

        . systress_0.3.0_amd64.deb (DEB)
        . systress-0.3.0-1.x86_64.rpm (RPM)
        . systress-0.3.0-Linux-systress.tar.gz (TGZ)
        . systress-0.3.0-Linux-systress.sh (STGZ)
        

Notes about RPM package
=======================

. Use the following to get information on a package file:

$ rpm -qp --info systress-0.3.0-1.x86_64.rpm
Name        : systress
Version     : 0.3.0
Release     : 1
Architecture: x86_64
[...]
License     : GPL/LGPL
Signature   : (none)
Source RPM  : systress-0.3.0-1.src.rpm
[...]
Relocations : /usr/local 
Vendor      : Rachid Koucha
URL         : http://systress.sourceforge.net
Summary     : SYSTRESS (System stress)
Description :
System loading and latency evaluation


. Use the following to get the pre/post-installation scripts in a package file:

$ rpm -qp --scripts rsys-0.3.0-1.x86_64.rpm
preinstall program: /bin/sh
postinstall scriptlet (using /bin/sh):

#!/bin/sh

INSTALL_PREFIX=/usr/local

FILE=${INSTALL_PREFIX}/lib/cmake/FindRsys.cmake
chmod 644  ${FILE}
[...]

. Use following to list the files for an INSTALLED package:

$ rpm -ql systress

. Use following to list the files in a package file:

$ rpm -ql systress-0.3.0-1.x86_64.rpm

. The required package list of an RPM file could be printed with:

$ rpm -qp --requires systress-0.3.0-1.x86_64.rpm




Notes about DEB package
=======================

. Use the following to get information on a package file:

$ dpkg --info systress_0.3.0_amd64.deb
[...]
 Package: systress
 Version: 0.3.0
 Section: devel
 Priority: optional
 Architecture: amd64
 Homepage: https://sourceforge.net/projects/systress/
[...]
 Maintainer: Rachid Koucha <rachid dot koucha at gmail dot com>
 Description: System loading and latency evaluation


. Use following to list the files in a package file:

$ dpkg -c systress_0.3.0_amd64.deb

. Use following to install the content of a package file:

$ sudo dpkg -i systress_0.3.0_amd64.deb

. Use the following to list the installed packages:

$ dpkg -l | grep systress

. Use following to uninstall (remove) a package:

$ sudo dpkg -r systress


===============================================================================

                                    DOCUMENTATION
                                    =============

On line manuals
===============

. Once SYSTRESS is installed, it is possible to access the corresponding
  on line manuals with:


$ man systress       # Manual of systress tool

$ man systress.conf  # Manual of systress configuration


===============================================================================

                                    REFERENCES
                                    ==========

* Introduction to autotools

http://freesoftwaremagazine.com/articles/brief_introduction_to_gnu_autotools/