ossp-pkg/platform/platform.pod
##
## OSSP platform - Unix Platform Identification
## Copyright (c) 2003 The OSSP Project <http://www.ossp.org/>
## Copyright (c) 2003 Ralf S. Engelschall <rse@engelschall.com>
##
## This file is part of OSSP platform, a Unix platform identification
## program which can be found at http://www.ossp.org/pkg/tool/platform/.
##
## 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.0 of the License, 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 library; if not, write to the Free Software
## Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
## USA, or contact Ralf S. Engelschall <rse@engelschall.com>.
##
## platform.pod: the manual page (language: Plain Old Document)
##
=pod
=head1 NAME
B<OSSP platform> - Unix Platform Identification
=head1 SYNOPSIS
B<platform>
[B<-F>|B<--format> I<FORMAT>]
[B<-S>|B<--sep> I<STRING>]
[B<-C>|B<--conc> I<STRING>]
[B<-L>|B<--lower>]
[B<-U>|B<--upper>]
[B<-v>|B<--verbose>]
[B<-c>|B<--concise>]
[B<-n>|B<--newline>]
[B<-d>|B<--debug>]
B<platform>
[B<-t>|B<--type> I<TYPE>]
[B<-n>|B<--newline>]
[B<-d>|B<--debug>]
B<platform>
[B<-V>|B<--version>]
B<platform>
[B<-h>|B<--help>]
=head1 DESCRIPTION
B<OSSP platform> is a flexible Unix platform identification program.
It distinguishes a platform according to its I<hardware architecture>
and I<operating system>. For both there is a I<class>, I<product> and
I<technology> identification. For each of those six identifications,
there is a I<verbose>, I<regular> and I<concise> version.
This leads to eighteen (2x3x3) available identification strings for each
platform, from which usually 2 are chosen in a particular situation.
This is done by assembling the platform identification string using a
I<FORMAT> string containing one or more identification constructs of the
forms "C<%[xx]>" (verbose), "C<%{xx}>" (regular) and "C<%E<lt>xxE<gt>>"
(concise).
=head1 OPTIONS
The following command line options are available.
=over 4
=item B<-F>, B<--format> I<FORMAT>
This option controls the output formatting of this program. It is a
plain-text string with the "C<%>I<xx>" constructs which expand to the
various platform information strings. "C<%{>I<xx>C<}>" is the canonical
regular version of the information. "C<%[>I<xx>C<]>" is the verbose
version of the information. "C<%E<lt>>I<xx>C<E<gt>>" is the concise
version of the information. In total, the following constructs
are available for expansion:
%[ac] verbose hardware architecture class
%{ac} regular hardware architecture class
%<ac> concise hardware architecture class
%[ap] verbose hardware architecture product
%{ap} regular hardware architecture product
%<ap> concise hardware architecture product
%[at] verbose hardware architecture technology
%{at} regular hardware architecture technology
%<at> concise hardware architecture technology
%[sc] verbose operating system class
%{sc} regular operating system class
%<sc> concise operating system class
%[sp] verbose operating system product
%{sp} regular operating system product
%<sp> concise operating system product
%[st] verbose operating system technology
%{st} regular operating system technology
%<st> concise operating system technology
The default I<FORMAT> string is "C<%{sp} (%{ap})>", providing the
regular operating system and hardware architecture product information.
=item B<-S>, B<--sep> I<STRING>
This option sets the word I<separation> string for the platform
information strings. By default it is "C< >" (whitespace). It is
especially used for separating the operating system name and
the operating system version.
=item B<-C>, B<--conc> I<STRING>
This option sets the word I<concatenation> string for the platform
information strings. By default it is "C</>". It is especially used to
concatenate multiple parts in operating system name and version parts.
=item B<-L>, B<--lower>
This options enforces conversion of the output to all I<lower> case.
=item B<-U>, B<--upper>
This options enforces conversion of the output to all I<upper> case.
=item B<-v>, B<--verbose>
This option enforces verbose versions of all expansion constructs
in I<FORMAT> string of option B<-F>. It is equal to specifying all
expansion constructs as "C<%[>I<xx>C<]>".
=item B<-c>, B<--concise>
This option enforces concise versions of all expansion constructs
in I<FORMAT> string of option B<-F>. It is equal to specifying all
expansion constructs as "C<%E<lt>>I<xx>C<E<gt>>".
=item B<-n>, B<--no-newline>
This option omits the usual trailing newline character in the output.
=item B<-t>, B<--type> I<TYPE>
This option is a meta option which internally sets options B<-F>, B<-S>,
B<-C>, B<-L>, B<-U>, B<-v> or B<-c> according to I<TYPE>. It can be used
to easily specify various commonly known outputs. The following I<TYPE>s
are available:
=over 4
=item B<binary>
Binary Package Id (OpenPKG RPM).
This is equal to "C<-F '%<ap>-%<sp>' -L -S '' -C '+'>"
and results in outputs like "C<ix86-freebsd4.9>" and "C<ix86-debian3.0>".
=item B<build>
Build-Time Checking (OpenPKG RPM).
This is equal to "C<-F '%<at>-%<st>' -L -S '' -C '+'>"
and results in outputs like "C<i686-freebsd4.9>" and "C<i586-linux2.4>".
=item B<gnu>
GNU F<config.guess> Style Id.
This is similar to B<build> and is equal to "C<-F '"%<at>-unknown-%<st>' -L -S '' -C '+'>"
and results in outputs like "C<i686-unknown-freebsd4.9>" and "C<i586-unknown-linux2.4>".
=item B<web>
HTTP Server Header Id.
This is equal to "C<-F '"%<sp>-%<ac>' -S '/' -C '+'>"
and results in outputs like "C<FreeBSD/4.9-iX86>" and "C<Debian/3.0-iX86>".
=item B<summary>
Human Readable Verbose Summary Information. This is equal to "C<-F
'Class: %[sc] (%[ac])\nProduct: %[sp] (%[ap])\nTechnology: %[st]
(%[at])' -S ' ' -C '/'>" and results in outputs like:
Class: 4.4BSD (iX86)
Product: FreeBSD 4.9-RC (iX86)
Technology: FreeBSD 4.9-RC (i686)
and
Class: LSB (iX86)
Product: Debian GNU/Linux 3.0 (iX86)
Technology: GNU/Linux 2.2/2.4 (i686)
=item B<all-in-one>
All-In-One Full-Table Information. This just outputs really
all 2x2x3 identification strings as a table.
=back
=item B<-d>, B<--debug>
This option enables some internal debugging messages.
=item B<-V>, B<--version>
This option outputs the version information of B<OSSP platform> only.
=item B<-h>, B<--help>
This option outputs the usage information of B<OSSP platform> only.
=back
=head1 EXAMPLES
The following real-life use cases are known:
=over 4
=item B<OpenPKG> build-time decisions
$ platform -c -L -S "" -C "+" -F "%at-%st"
$ platform -c -L -S "" -C "+" -F "%ac-%sc"
=item B<OpenPKG> binary RPM packages
$ platform -c -L -S "" -C "+" -F "%ap-%sp"
=item F<README> files
$ platform -v -F "%sp (%ap)"
$ platform -v -F "%sc (%ac)"
=item Debugging
$ platform --type=all-in-one
=back
=head1 SUPPORT
B<OSSP platform> currently knows the following particular Unix platforms
in detail: FreeBSD, NetBSD, OpenBSD, Linux, Sun Solaris, SCO UnixWare,
QNX Neutrino, SGI IRIX, HP HP-UX, HP Tru64, IBM AIX and Apple MacOS X
Darwin.
All other Unix platforms are recognized through generic uname(1)
information and so usually can be identified sufficiently, although the
identification might be not as precise as possible.
=head1 SEE ALSO
http://www.ossp.org/pkg/tool/platform/.
uname(3), GNU F<config.guess>.
=head1 HISTORY
B<OSSP platform> was implemented in September 2003 by I<Ralf S.
Engelschall> for use in the B<OSSP> and B<OpenPKG> projects. It was
prompted by the need in B<OpenPKG> to have both product (for RPM
filenames) and technology (for build-time decisions) identifiers for the
Unix platforms, OpenPKG packages are maintained for. It was inspired by
the B<GNU> F<config.guess> and the old B<GNU shtool> F<guessos> command.
The major difference to B<GNU> F<config.guess> is that B<OSSP platform>
does not use a I<vendor> identification (cannot be determined most of
the time and is not used at all in all projects I've ever seen) and
is a lot more flexible (class, product and technology identifications
combined with verbose, regular and concise outputs). The drawback of
B<OSSP platform> is that it (still) knows less particular platforms,
although the generic platform identification is sufficient enough most
of the time.
=head1 AUTHOR
Ralf S. Engelschall
rse@engelschall.com
www.engelschall.com
=cut
