=pod

=head1 NAME

sysarch - defines system specific variables using the uname system command

=head1 SYNOPSIS

sysarch [OPTION]... [VARIABLE] [VARIABLE]

=head1 DESCRIPTION

B<sysarch> provides a uniform description of a system, including the
underlying hardware, the operating system, and the unique operating
system characteristics.  Its intent is to identify important system
characteristics which determine the interoperability of software with
hardware/operating system platforms.

Compatibility between operating systems sometimes occurs.  Solaris is
a true champion of this, retaining compatibility across more than a
decade in some cases.  It's also often possible to run programs
compiled on one flavor of Linux on another.  It is rare for software
compiled on newer platforms to run on older ones, however.  While
B<sysarch> can't determine which systems are compatible, it tries to
present enough salient information so that it is possible to provide a
hierarchy of compatibility.

B<sysarch> encodes system information into a set of variables.  It
will generate code for various shells and GNU make which can be used
to incorporate those variables into scripts and Makefiles.

=head1 OPTIONS AND ARGUMENTS

B<sysarch> takes an optional argument specifying the name of a
variable to output. If no options or arguments are specified they are
all output.

=head2 General Options

=over 4

=item B<--export>

Output code which creates environmental, rather than shell, variables.
Only releveant for shells.

=item B<--pfx> I<pfx>

Prepend I<pfx> to variable names.

=item B<--help>

Print this usage information and exit.

=back

=head2 Output Formats

Output formats are specified either using the B<--output> option, or
simply by prefixing the format name with C<--> and treating it as an
option:

   --output csh
   --csh

If no variables are specified on the command line, the default output
format is C<nice>.  If variables are specified, it defaults to C<value>.


The following formats are supported:

=over

=item B<csh>|B<tcsh>|B<sh>|B<ksh>| B<bash>

Output commands in the appropriate shell to create the variables.

=item B<make>

Create static B<make> compatible macro assignments.  Macro names are
in upper case.

=item B<gmake_extract>

Create dynamic GNU B<make> compatible macro assignments using a call
to B<sysarch>. Macro names are in upper case.

=item B<gmake_cat>

Create the output required by the code output by C<--output
gmake_extract>.

=item B<make_dump>

Generate B<make> target commands to output the B<sysarch> generated
macros.  Useful as part of a B<make> C<debug> style target.

=item B<perl>

Output Perl code generating scalar variables.

=item B<perl_hash>

Output Perl code for the contents of a hash.  It does not generate the
wrapper code required to actually create the hash.

=item B<value>

Output only the variables' values.

=item B<nice>

A more human readable format.

=back


=head1 OUTPUT VARIABLES


=head2 Hardware Identification

=over

=item B<hw_cpu>

The most specific description of the actual CPU.

=item B<hw_cpu_generic>

The generic description for the CPU.  This is I<not> the most generic
one with which the CPU is compatible.  For example,

    athlon_64 => x86_64,  not i686
    core2     => x86_64,  not i686
    pentium4  => i686
    ultra3i   => sun4u,   not sparc

=item B<hw_cpus>

A colon separated list of models or families of CPU's with which the
hardware is compatible, from least to most generic.

=back

For example, for a SunBlade 1500,

  hw_cpu  = ultra3i
  hw_cpus = ultra3i:sun4u:sun4m:sparc

For an AMD Athlon64 CPU,

  hw_cpu  = athlon_64
  hw_cpus = athlon_64:x86_64:i686


=head2 System Identification

The system designation represents the combination of operating system,
kernel, and optionally vendor or distribution name.

=over

=item B<OS>, B<os_type>

The operating system name.  B<OS> has historical significance for
Linux and Solaris, and retains the following value for them:

  Linux
  SunOS

For other operating systems, B<OS> and B<os_type> are equivalent.
B<os_type> is the lowercased more "obvious" name (i.e. C<solaris>
rather than C<sunos>) and is typically equivalent to the B<OSTYPE>
environmental variable.

Note that C<Linux> represents both the kernel and the accompanying
system software.  This is often represented as GNU/Linux, similar to
Debian GNU/kFreeBSD, Debian GNU/NetBSD, GNU/Hurd and Debian
GNU/Solaris.  The latter set aren't available to the authors, so we're
not worrying about them yet.

=item B<os_vendor>

B<os_vendor> is the vendor or distribution name.  Some vendors provide
multiple distributions (e.g. Red Hat Fedora Core, Red Hat Enterprise
Linux) -- B<os_vendor> is then the combination (e.g. C<RHFC>, C<RHEL>).

=back


=head2 System Version

System version information is complex.  It might refer to the version
given to a particular distribution or release (such as Fedora Core 3
or 4).  For some applications the kernel version is more important, or
perhaps the version of glibc. B<sysarch> provides all of that
information.

=over

=item B<kern_version>

B<kern_version> is the kernel version.  On Linux it is the base kernel,
without any vendor specific version information.

=item B<kern_version_maj>

B<kern_version_maj> contains just the most significant kernel version
(e.g. 2.6 for Linux, 8.8 for Darwin).

=item B<kern_versions>

A colon separated list of kernels with which this is compatible.

=item B<os_version>, B<os_version_maj>

B<os_version> is the vendor supplied operation system version.
B<os_version_maj> is the most significant part (e.g, for OSX 10.4
vs. 10.4.8).

=item B<os_versions>

A colon separated list of operating system versions with which this
operating system is backwards compatible.

=item B<os_uversion>, B<os_uversion_maj>

The version of the operating system component most important for user
space applications.  For Linux this is chosen to be the version of
glibc.  This may not be restrictive enough for some applications
(e.g. if one distribution ships with a different version of
B<libreadline>). B<os_version_maj> is the most significant part (e.g.,
2.3 vs. 2.3.6).

=item B<os_uversions>

A colon separated list of user space component versions with which
this operating system is backwards compatible.  For Linux it is
assumed that previous minor (in the glibc sense) releases are
backwards compatible.

=back

=head2 Platform

A platform is the combination of hardware and operating system
specifications.  It's a triad with one of the following combinations:

  <hw_cpu>-<os_type>-<os_uversion>
  <hw_cpu>-<OS>-<os_version>

where C<E<lt>OSE<gt>> is

 <os_type>_<os_vendor>

except for Solaris and OSX (Darwin) where it is

 <os_type>

It is assumed that B<os_uversion> is constant for a given
B<os_version>.

=head3 Host System

These variables describe the host system's platform

=over

=item B<platform>

=item B<platform_native>

Aliases for B<platform_os_native>.

=item B<platform_generic>

An alias for B<platform_uos_generic>.

=item B<platform_os_native>

The most detailed specification including the OS vendor/distribution.
Equivalent to

  <hw_cpu>-<OS>-<os_version>

=item B<platform_os_generic>

This specification allows for a more generic hardware and OS
specification, allowing for compatibility within minor OS and
hardware variations.  This is equivalent to

  <hw_cpu_generic>-<OS>-<os_version_maj>

=item B<platform_uos_native>

The most detailed specification using the user space component version.
Equivalent to

  <hw_cpu>-<os_type>-<os_uversion>

=item B<platform_uos_generic>

Equivalent to

  <hw_cpu_generic>-<OS>-<os_uversion_maj>

=back

=head3 Compatible platforms

These variables provide lists of compatible platforms

=over

=item B<platforms>

A colon separated list of compatible platforms, with hardware being
the most important element for compatibility.  This is a combination
of B<platforms_os> and B<platforms_uos>.


=item B<platforms_os>

A colon separated list of compatible platforms of the form

  <hw_cpu>-<OS>-<os_version>

With Hardware being the most important element for compatibility.


=item B<platforms_uos>

A colon separated list of compatible platforms of the form

  <hw_cpu>-<os_type>-<os_uversion>

with hardware being the most important element for compatibility.

=back

=head1 WHAT DOES THIS ALL MEAN?

Well, that depends upon how its being used.  First off, use
B<platforms> and B<sysarch>'s accompanying B<syspathsubst>
program to create compatibility hierarchies for executable and library
search paths.

B<platform_generic> is B<not> the lowest common denominator.  It's
essentially the most generic specification that can be natively
created (i.e. compiled) on the platform.  Because it purports to
specify user space compatibility, use it on Linux if you're sure that
your application will run on multiple Linux distributions based solely
on B<glibc> compatibility.  If, however, your application links
against libraries in a combination that differs between distributions,
you might as well use B<platform_os_generic>.

=head1 COPYRIGHT AND LICENSE

This software is Copyright 2007 The Smithsonian Astrophysical Observatory
and is released under the GNU General Public License.  You may find a
copy at: L<http://www.fsf.org/copyleft/gpl.html>


=head1 AUTHORS

M. Tibbetts E<lt>mtibbetts@cfa.harvard.eduE<gt>

D. Jerius   E<lt>djerius@cfa.harvard.eduE<gt>
