cd9d9eb42b
git-svn-id: https://svn.code.sf.net/p/xcat/code/xcat-core/trunk@792 8638fb3e-16cb-4fca-ae20-7b5d299a9bcd
284 lines
9.3 KiB
Perl
Executable File
284 lines
9.3 KiB
Perl
Executable File
#!/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
|
|
|
|
xCAT also supports regular expressions in the tables. This enables one row to represent many
|
|
rows. 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;
|
|
} |