#
# SysView: User Guide
#
# Copyright (c) 2004 Pravin Damle. All Rights Reserved
#
# Author: Pravin Damle
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2, or (at your option)
# any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; see the file COPYING. If not, write to
# the Free Software Foundation, 59 Temple Place - Suite 330,
# Boston, MA 02111-1307, USA.
#
-------------------------------------------------------------------------------
*CONTENTS*
* Introduction
* High Level Design
* DOWNLOAD Steps
* BUILD Steps
* Running SysView
All commands shown in this document assume that your command shell is bash.
-------------------------------------------------------------------------------
*Introduction*
__Brief Description__
SysView is a Java application to help Linux Administrators "see"
system administration related directories, configuration files
and other kernel parameters.
__Motivation__
A Linux System Administrator must have apriori knowledge of all aspects that need
administration/configuration. This is not a trivial undertaking.
Even if the Administrator has adequate knowledge, that person has to manually
navigate through the directory structure and browse the relevant files.
SysView will help in both knowledge and navigation
of Linux System Administration related configuration files.
SysView will be bundled with a configuration file that will contain
information about several other configuration files.
SysView will also have the capability to search for configuration files
with standard names in standard directories for such files.
SysView will have a Graphical User Interface to allow for
convenient navigation and viewing of the configuration files.
__Final Vision__
The initial form of SysView needs a hand crafted configuration file.
Maintenance of such a file by a small group of developers
is not scalable with respect to the ever increasing
number of open source applications.
To solve this problem, during application/module installation,
the module "registers" itself in the appropriate category with SysView.
This enables applications to self classify them in the SysView configuration file
and makes the task of maintaining the SysView configuration file scalable
I am currently not envisioning SysView to take
on the role of system configuration.
-------------------------------------------------------------------------------
*High Level Design*
__Description__
SysView is a Java application that presents in a well classified way
the various directories, configuration files and other kernel parameters
in a Graphical User Interface.
How does the Java application achieve the above task?
The Java application reads (using JLex and CUP based parser)
a configuration file (that classifies and lists all administration
related config files, dirs, etc)
and constructs an internal tree-like data structure with the read information.
This information is presented using Java Swing components.
Where does the configuration file exist?
At some predetermined location (which is hardcoded into the Java application).
Who maintains the information in the configuration file?
Initially, the configuration file will be created by the developer of this application.
It will contain information about most of the frequently accessed system administration parameters.
SysView will also provide a command line interface to update the configuration file directly.
This interface will be used by applications/modules/etc to keep the configuration file up-to-date.
The command line interface currently in design phase.
__Architectural Components__
-----------------------
| GUI | CLI |
-----------------------
| Parser |
-----------------------
| SysView config file |
-----------------------
-------------------------------------------------------------------------------
*DOWNLOAD Steps*
1. download latest release of sysview.tar
from http://sourceforge.net/projects/sysview/
to your home directory
2. untar sysview.tar
this should create the directory sysview in your home directory
3. Download steps for CUP
cd $HOME
mkdir CUPJLEX
mkdir CUPJLEX/CUP
download CUP 0.10k from http://www.cs.princeton.edu/~appel/modern/java/CUP/ to $HOME/CUPJLEX/CUP
unzip and untar that file.
This will create (among other files) the directory $HOME/CUPJLEX/CUP/java_cup
4. download steps for JLEX
cd $HOME
mkdir CUPJLEX/JLex
download source code version 1.2.6 of JLex
from http://www.cs.princeton.edu/~appel/modern/java/JLex/ to $HOME/CUPJLEX/JLex
It is a single file called Main.java
Note: You can choose to place sysview, CUP and JLEX in different locations.
In that case you will need to modify the BUILD steps accordingly.
-------------------------------------------------------------------------------
*BUILD Steps*
Assuming that you completed the DOWNLOAD Steps.
Assuming that you have Java SDK version 1.4.2 or higher.
I have tested it only with version 1.4.2, so I cannot vouch for other versions.
__Setting up environment__
1. Setup the CLASSPATH environment variable such that it includes the following paths
the base directory for java
$HOME/CUPJLEX
$HOME/CUPJLEX/CUP
$HOME/sysview/classes
I have set it up by including the following in my .bashrc
export CLASSPATH=$HOME/j2sdk_nb/j2sdk1.4.2:$HOME/CUPJLEX:$HOME/CUPJLEX/CUP:$HOME/sysview/classes
2. Make sure that the java and javac binaries are accessible from your PATH environment variable
3. Make sure that make, find, gawk and sed are also accessible from your PATH environment variable
make is required.
find, gawk and sed are required for only some targets in the makefile.
4. Follow the compilation instructions for JLEX
In summary they are as follows (but please check with JLex documentation for the real instructions)
cd $HOME/CUPJLEX/JLex
javac Main.java
__Building SysView__
Assuming that the environment is setup as described above, the steps are
cd $HOME/sysview
make
-------------------------------------------------------------------------------
*Running SysView*
Assuming that you completed the DOWNLOAD and BUILD Steps,
the steps for running Sysview are
cd $HOME/sysview
java SysView config/sysview.conf
The makefile contains 2 targets for running sysview.
The first is called "run" and the second is called "run2"
To invoke run2 type "make run2" at the command prompt.
The target "run" is just "java SysView config/sysview.conf"
config/sysview.conf is the standard configuration file for SysView.
It is constructed mostly by hand.
It lists and classifies several linux system administration related configuration files.
If you would like to see some specific configuration file to appear in the
standard sysview configuration file, then please send the file's name and location
in the file system along with its category to pravindamle AT users.sourceforge.net
The target "run2" however does a lot more than "run"
"run2" searches for configuration files in the file system and
presents all those along with all the pre-defined information in
config/sysview.conf file.
To do this, It invokes the command "cmd/getallconf"
to search for (using find command) configuration files
in various directories ( like /etc or /usr).
Then it uses (gawk and sed commands are required) the results of this
search to construct a new configuration file in the sysview configuration file format.
This file is then combined with the config/sysview.conf file to produce config/all.conf.
Then it invokes SysView with this configuration file.
Please take a look at getallconf file. you can modify this file
to make it look for more kinds of configuration files.
You could also send that information to pravindamle AT users.sourceforge.net for SysView
so that it could be included in then next release of SysView.
-------------------------------------------------------------------------------