xcat-core/perl-xCAT/db2man

#!/usr/bin/perl
# IBM(c) 2007 EPL license http://www.eclipse.org/legal/epl-v10.html

# Builds the xCAT database man pages from the descriptions that are contained
# in Schema.pm.  This script is run during the build of the perl-xCAT rpm, but
# is not packaged in the binary form of that rpm.

# We assume that this script is run in the perl-xCAT-2.0 dir, so everything is
# done relative to that.

use strict;
use lib '.';

use xCAT::Schema;
use xCAT::Table;
use Pod::Man;
use Pod::Html;

my $poddir = 'pods';
my $mandir = 'share/man';
my $htmldir = 'share/doc';

my $poddir5 = 'pods/man5';
if (system("mkdir -p $poddir5")) { die "Error: could not create $poddir5.\n"; }

# Build the DB overview page.
print "Building PODs pages for the database tables...\n";
writesummarypage("$poddir5/xcatdb.5.pod", xCAT::Table->getDescriptions()),

# Build the pod man page for each table.
my $tabspecref = \%xCAT::Schema::tabspec;
foreach my $tablekey (keys %$tabspecref) {
    my $table = $tabspecref->{$tablekey};
    my $summary = $table->{table_desc};
    my $colorder = $table->{cols};
    my $descriptions = $table->{descriptions};
    writepodmanpage("$poddir5/$tablekey.5.pod", $tablekey, $summary, $colorder, $descriptions);
}

my @pods = getPodList($poddir);
#foreach (@pods) { print "$_\n"; } exit;

# Build the man page for each pod.
#mkdir($mandir) or die "Error: could not create $mandir.\n";
print "Converting PODs to man pages...\n";
foreach my $podfile (@pods) {
    my $manfile = $podfile;
    $manfile =~ s/^$poddir/$mandir/;      # change the beginning of the path
    $manfile =~ s/\.pod$//;			# change the ending
    my $mdir = $manfile;
    $mdir =~ s|/[^/]*$||;			# get rid of the basename part
	if (system("mkdir -p $mdir")) { die "Error: could not create $mdir.\n"; }
	my ($section) = $podfile =~ /\.(\d+)\.pod$/;
    convertpod2man($podfile, $manfile, $section);
}

# Build the html page for each pod.
#mkdir($htmldir) or die "Error: could not create $htmldir.\n";
print "Converting PODs to HTML pages...\n";
foreach my $podfile (@pods) {
    my $htmlfile = $podfile;
    $htmlfile =~ s/^$poddir/$htmldir/;      # change the beginning of the path
    $htmlfile =~ s/\.pod$/\.html/;			# change the ending
    my $hdir = $htmlfile;
    $hdir =~ s|/[^/]*$||;			# get rid of the basename part
	if (system("mkdir -p $hdir")) { die "Error: could not create $hdir.\n"; }
    convertpod2html($podfile, $htmlfile, $poddir, $htmldir);
}

exit;


# Recursively get the list of pod man page files.
sub getPodList {
	my $poddir = shift;
	my @files;

	# 1st get toplevel dir listing
	opendir(DIR, $poddir) or die "Error: could not read $poddir.\n";
	my @topdir = grep !/^\./, readdir(DIR);
	close(DIR);

	# Now go thru each subdir (these are man1, man3, etc.)
	foreach my $mandir (@topdir) {
		opendir(DIR, "$poddir/$mandir") or die "Error: could not read $poddir/$mandir.\n";
		my @dir = grep !/^\./, readdir(DIR);
		close(DIR);
		foreach my $file (@dir) {
			push @files, "$poddir/$mandir/$file";
		}
	}
	return sort @files;
}


# Create the html page for one pod.
sub convertpod2html {
	my ($podfile, $htmlfile, $poddir, $htmldir) = @_;

	#TODO: use --css=<stylesheet> and --title=<pagetitle> to make the pages look better
	pod2html($podfile,
			"--outfile=$htmlfile",
			"--podpath=man5",
			"--podroot=$poddir",
			"--htmldir=$htmldir",
			"--recurse",
			"--cachedir=/tmp",
			);

}


# Create the man page for one pod.
sub convertpod2man {
	my ($podfile, $manfile, $section) = @_;

	my $parser = Pod::Man->new(section => $section);
    $parser->parse_from_file($podfile, $manfile);
}


# Create the xcatdb man page that gives a summary description of each table.
sub writesummarypage {
	my $file = shift;       # relative path file name of the man page
	my $descriptions = shift;	# a hash containing the description of each table

	open(FILE, ">$file") or die "Error: could not open $file for writing.\n";

	print FILE <<'EOS1';
=head1 NAME

An overview of the xCAT database.

=head1 DESCRIPTION

The xCAT database contains user settings for the cluster and information gathered from the cluster.
It consists of a series of tables, which are described below.  To get more information about a
particular table, run man for that table name.  The tables can be manipulated directly using the
B<tabedit> or B<chtab> commands.  They can be viewed using B<nodels> or B<tabdump>.

xCAT allows the use of different database applications, depending on the needs of your cluster.
The default database is SQLite, which is a daemonless, zero-config database.  But you could instead
choose to use something like postgresql for greater scalability and remote access in the
hierarchical/service node case.  To use a different database or a different location, create
the file /etc/xcat/cfgloc.  The first line of the file should contain something like one of the examples
below:

=over 4

=item SQLite:/var/xcat/cfg

=item Pg:dbname=xcat;host=<mgmtnode>|<pguserid>|<pgpasswd>

where mgmtnode is the hostname of the management node adapter on the cluster side

=back

The xCAT database spans a number of tables, some with records associated with particular nodes
(such as nodelist and nodehm) and others that do not have a direct relationship with any given node.
The tables not associated with a given node are straightforward, the data is stored and retrieved
as-is from the database without interpretation, and without any generic inheritance
(though some calling code may implement inheritance for specific fields, for example
nodehm.power inheriting from nodehm.mgt).

The tables with records typically retrieved by node name have some extra features to enable a more
template-based style to be used:

Any group name can be used in lieu of a node name in the node field, and that record will then
be taken to be applicable to any node in that group.  If a field is requested for a specific node,
and either a record doesn't exist specifically for that nodename or a record exists, but has no
definition for the requested field, that node's groups are then used to search for
records.  If multiple records could apply from two different groups, the precedence is
the order the groups are specified in the nodelist table for that node.  This is nearly identical to
most xCAT 1.x tab file conventions.  This is useful in tables such as noderes, where typical
configurations have exactly the same field values for large sets of nodes.

xCAT 2 extends the above to be made useful where a field will vary for every node with a given tag,
but in ways that would be trivial to describe.  If a field is of the format /I<pattern>/I<replacement>/,
it is taken to be a perl regular expression, to be performed on the nodename.  For example, the bmc field
of the ipmi table might be B</\z/-bmc/> for a record with node=ipmi to specify that the BMC hostname is derived
by appending B<-bmc> to the end of the nodename of every node in the ipmi group.

As an extension to the above, a regular expression extended with arithmetic operators is available,
by using the format |I<pattern>|I<replacement>|.  This behaves similarly to the above, but () enclosed parts
in I<replacement> are taken to signify arithmetic operations and substituted in.  All operations are integer
arithmetic, so 5/4 would come out as 1.  The typical perl positional variables are available in such expressions.

For example, if you have many blades in your cluster and their hostnames have a regular
pattern of blade1, blade2, etc., and your BladeCenter management modules also have a hostname
pattern of amm1, amm2, etc., then your B<mp> table could be expressed by the following single row:

  "blade","|\D+(\d+)|amm(($1-1)/14+1)|","|\D+(\d+)|(($1-1)%14+1)|",,

Before you panic, let me explain each column:

=over 4

=item B<blade>

This is a group name.  In this example, we are assuming that all of your blades belong to this
group.  Each time the xCAT software accesses the B<mp> table to get the management module and slot number
of a specific blade (e.g. B<blade20>), this row will match (because B<blade20> is in the B<blade> group).
Once this row is matched for B<blade20>, then the processing described in the following items will take
place.

=item B<|\D+(\d+)|amm(($1-1)/14+1)|>

This is a perl substitution pattern that will produce the value for the second column of the table (the
management module hostname).
The text B<\D+(\d+)> between the 1st two vertical bars is
a regular expression that matches the node
name that was searched for in this table (in this example B<blade20>).  The text that matches
within the 1st set of parentheses is set to $1.  (If there was a 2nd set of parentheses, it would
be set to $2, and so on.)  In our case, the \D+ matches the non-numeric part of the name
(B<blade>) and the \d+ matches the numeric part (B<20>).  So $1 is set to B<20>.  The text B<amm(($1-1)/14+1)> between the
2nd and 3rd vertical bars produces the string that should be used as the value
for this column in a hypothetical row for blade20.  Since $1 is set to 20, the expression B<($1-1)/14+1> equals
19/14 + 1, which equals 2.  Therefore the whole string is B<amm2>, which will be used as the hostname
of the management module.

=item B<|\D+(\d+)|(($1-1)%14+1)|>

This item is similar to the one above.  This substituion pattern will produce the value for
the 3rd column (the BladeCenter chassis slot number for this blade).  Because this row was
the match for B<blade20>, the parentheses
within the 1st set of vertical bars will set $1 to 20.  Since % means modulo division, the
expression B<($1-1)%14+1> will evaluate to 6.

=back

See http://www.perl.com/doc/manual/html/pod/perlre.html for information on perl regular expressions.

Because it can get confusing what attributes need to go in what tables, the xCAT database can also
be viewed and edited as logical objects, instead of flat tables.  Run B<lsdef> to see the list of
objects supported by xCAT.  Use B<mkdef>, B<chdef>, and B<rmdef> to create, change, and delete objects.
When using these commands, the object attributes will be stored in the same tables, as if you edited
the tables by hand.  The only difference is that the object commands take care of knowing which tables
all of the information should go in.

=head1 TABLES

=over 2
EOS1

foreach my $table (sort keys %$descriptions) {
	print FILE "\n=item L<$table(5)|$table.5>\n\n".$descriptions->{$table}."\n";
}

	print FILE <<"EOS3";

=back

=head1 SEE ALSO

B<nodels(1)>, B<chtab(8)>, B<tabdump(8)>, B<tabedit(8)>, B<lsdef(1)>, B<mkdef(1)>, B<chdef(1)>, B<rmdef(1)>
EOS3

	close FILE;
}


# Create the man page for one table.
sub writepodmanpage {
	my $file = shift;       # relative path file name of the man page
	my $tablename = shift;		# name of table
	my $summary = shift;		# description of table
	my $colorder = shift;		# the order in which the table attributes should be presented in
	my $descriptions = shift;	# a hash containing the description of each attribute

	open(FILE, ">$file") or die "Error: could not open $file for writing.\n";

	print FILE <<"EOS1";
=head1 NAME

B<$tablename> - a table in the xCAT database.

=head1 SYNOPSIS

B<$tablename Attributes:>
EOS1

foreach my $a (@$colorder) { print FILE "  I<$a>\n"; }

	print FILE <<"EOS2";

=head1 DESCRIPTION

$summary

=head1 $tablename Attributes:

=over 10

EOS2

foreach my $a (@$colorder) {
	my $d = $descriptions->{$a};
	$d =~ s/\n/\n\n/;      # if there are newlines, double them so pod sees a blank line, otherwise pod will ignore them
	#print FILE "\nB<$a> - $d\n";
	print FILE "\n=item B<$a>\n\n$d\n";
}

	print FILE <<"EOS3";

=back

=head1 SEE ALSO

B<nodels(1)>, B<chtab(8)>, B<tabdump(8)>, B<tabedit(8)>
EOS3

	close FILE;
}