util/src/TclTk/tcl8.6.12/doc/platform.n

   1 '\"
   2 '\" Copyright (c) 2006 ActiveState Software Inc
   3 '\"
   4 '\" See the file "license.terms" for information on usage and redistribution
   5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   6 '\"
   7 .TH "platform" n 1.0.4 platform "Tcl Bundled Packages"
   8 .so man.macros
   9 .BS
  10 '\" Note:  do not modify the .SH NAME line immediately below!
  11 .SH NAME
  12 platform \- System identification support code and utilities
  13 .SH SYNOPSIS
  14 .nf
  15 \fBpackage require platform ?1.0.10?\fR
  16 .sp
  17 \fBplatform::generic\fR
  18 \fBplatform::identify\fR
  19 \fBplatform::patterns \fIidentifier\fR
  20 .fi
  21 .BE
  22 .SH DESCRIPTION
  23 .PP
  24 The \fBplatform\fR package provides several utility commands useful
  25 for the identification of the architecture of a machine running Tcl.
  26 .PP
  27 Whilst Tcl provides the \fBtcl_platform\fR array for identifying the
  28 current architecture (in particular, the platform and machine
  29 elements) this is not always sufficient. This is because (on Unix
  30 machines) \fBtcl_platform\fR reflects the values returned by the
  31 \fBuname\fR command and these are not standardized across platforms and
  32 architectures. In addition, on at least one platform (AIX) the
  33 \fBtcl_platform(machine)\fR contains the CPU serial number.
  34 .PP
  35 Consequently, individual applications need to manipulate the values in
  36 \fBtcl_platform\fR (along with the output of system specific
  37 utilities) - which is both inconvenient for developers, and introduces
  38 the potential for inconsistencies in identifying architectures and in
  39 naming conventions.
  40 .PP
  41 The \fBplatform\fR package prevents such fragmentation - i.e., it
  42 establishes a standard naming convention for architectures running Tcl
  43 and makes it more convenient for developers to identify the current
  44 architecture a Tcl program is running on.
  45 .SH COMMANDS
  46 .TP
  47 \fBplatform::identify\fR
  48 .
  49 This command returns an identifier describing the platform the Tcl
  50 core is running on. The returned identifier has the general format
  51 \fIOS\fR-\fICPU\fR. The \fIOS\fR part of the identifier may contain
  52 details like kernel version, libc version, etc., and this information
  53 may contain dashes as well.  The \fICPU\fR part will not contain
  54 dashes, making the preceding dash the last dash in the result.
  55 .TP
  56 \fBplatform::generic\fR
  57 .
  58 This command returns a simplified identifier describing the platform
  59 the Tcl core is running on. In contrast to \fBplatform::identify\fR it
  60 leaves out details like kernel version, libc version, etc. The
  61 returned identifier has the general format \fIOS\fR-\fICPU\fR.
  62 .TP
  63 \fBplatform::patterns \fIidentifier\fR
  64 .
  65 This command takes an identifier as returned by
  66 \fBplatform::identify\fR and returns a list of identifiers describing
  67 compatible architectures.
  68 .SH EXAMPLE
  69 .PP
  70 This can be used to allow an application to be shipped with multiple builds of
  71 a shared library, so that the same package works on many versions of an
  72 operating system. For example:
  73 .PP
  74 .CS
  75 \fBpackage require platform\fR
  76 # Assume that app script is .../theapp/bin/theapp.tcl
  77 set binDir [file dirname [file normalize [info script]]]
  78 set libDir [file join $binDir .. lib]
  79 set platLibDir [file join $libDir [\fBplatform::identify\fR]]
  80 load [file join $platLibDir support[info sharedlibextension]]
  81 .CE
  82 .SH KEYWORDS
  83 operating system, cpu architecture, platform, architecture
  84 '\" Local Variables:
  85 '\" mode: nroff
  86 '\" End: