'\"
'\" Copyright (c) 2006 ActiveState Software Inc
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.TH "platform" n 1.0.4 platform "Tcl Bundled Packages"
.so man.macros
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
platform \- System identification support code and utilities
.SH SYNOPSIS
.nf
\fBpackage require platform\fR ?\fB1.0.10\fR?

\fBplatform::generic\fR
\fBplatform::identify\fR
\fBplatform::patterns \fIidentifier\fR
.fi
.BE
.SH DESCRIPTION
.PP
The \fBplatform\fR package provides several utility commands useful
for the identification of the architecture of a machine running Tcl.
.PP
Whilst Tcl provides the \fBtcl_platform\fR array for identifying the
current architecture (in particular, the platform and machine
elements) this is not always sufficient. This is because (on Unix
machines) \fBtcl_platform\fR reflects the values returned by the
\fBuname\fR command and these are not standardized across platforms and
architectures. In addition, on at least one platform (AIX) the
\fBtcl_platform(machine)\fR contains the CPU serial number.
.PP
Consequently, individual applications need to manipulate the values in
\fBtcl_platform\fR (along with the output of system specific
utilities) - which is both inconvenient for developers, and introduces
the potential for inconsistencies in identifying architectures and in
naming conventions.
.PP
The \fBplatform\fR package prevents such fragmentation - i.e., it
establishes a standard naming convention for architectures running Tcl
and makes it more convenient for developers to identify the current
architecture a Tcl program is running on.
.SH COMMANDS
.\" COMMAND: identify
.TP
\fBplatform::identify\fR
.
This command returns an identifier describing the platform the Tcl
core is running on. The returned identifier has the general format
\fIOS\fR-\fICPU\fR. The \fIOS\fR part of the identifier may contain
details like kernel version, libc version, etc., and this information
may contain dashes as well.  The \fICPU\fR part will not contain
dashes, making the preceding dash the last dash in the result.
.\" COMMAND: generic
.TP
\fBplatform::generic\fR
.
This command returns a simplified identifier describing the platform
the Tcl core is running on. In contrast to \fBplatform::identify\fR it
leaves out details like kernel version, libc version, etc. The
returned identifier has the general format \fIOS\fR-\fICPU\fR.
.\" COMMAND: patterns
.TP
\fBplatform::patterns \fIidentifier\fR
.
This command takes an identifier as returned by
\fBplatform::identify\fR and returns a list of identifiers describing
compatible architectures.
.SH EXAMPLE
.PP
This can be used to allow an application to be shipped with multiple builds of
a shared library, so that the same package works on many versions of an
operating system. For example:
.PP
.CS
\fBpackage require platform\fR
# Assume that app script is .../theapp/bin/theapp.tcl
set binDir [file dirname [file normalize [info script]]]
set libDir [file join $binDir .. lib]
set platLibDir [file join $libDir [\fBplatform::identify\fR]]
load [file join $platLibDir support[info sharedlibextension]]
.CE
.SH KEYWORDS
operating system, cpu architecture, platform, architecture
'\" Local Variables:
'\" mode: nroff
'\" End:
