diff options
| -rw-r--r-- | ChangeLog | 3 | ||||
| -rw-r--r-- | doc/platform.n | 68 | ||||
| -rw-r--r-- | doc/platform_shell.n | 59 |
3 files changed, 130 insertions, 0 deletions
@@ -15,6 +15,9 @@ * library/platform/shell.tcl: * library/platform/pkgIndex.tcl: + * doc/platform.n: + * doc/platform_shell.n: + 2006-12-05 Don Porter <dgp@users.sourceforge.net> * generic/tclPkg.c: When no requirements are supplied to a diff --git a/doc/platform.n b/doc/platform.n new file mode 100644 index 0000000..827e188 --- /dev/null +++ b/doc/platform.n @@ -0,0 +1,68 @@ +'\" +'\" Copyright (c) 2006 ActiveState Software +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id: platform.n,v 1.1 2006/12/05 18:46:59 andreas_kupries Exp $ +'\" +.so man.macros +.TH "platform" n 1.0.2 platform "Tcl Bundled Packages" +.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 ?1.0.2?\fR +.sp +\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 aren't 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 +.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. +.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. +.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 KEYWORDS +operating system, cpu architecture, platform, architecture diff --git a/doc/platform_shell.n b/doc/platform_shell.n new file mode 100644 index 0000000..d8ef12a --- /dev/null +++ b/doc/platform_shell.n @@ -0,0 +1,59 @@ +'\" +'\" Copyright (c) 2006 ActiveState Software +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id: platform_shell.n,v 1.1 2006/12/05 18:47:00 andreas_kupries Exp $ +'\" +.so man.macros +.TH "platform::shell" n 1.0.2 platform::shell "Tcl Bundled Packages" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +platform::shell \- System identification support code and utilities +.SH SYNOPSIS +.nf +\fBpackage require platform::shell ?1.0.1?\fR +.sp +\fBplatform::shell::generic \fIshell\fR +\fBplatform::shell::identify \fIshell\fR +\fBplatform::shell::platform \fIshell\fR +.fi +.BE +.SH DESCRIPTION +.PP +The \fBplatform::shell\fR package provides several utility commands useful +for the identification of the architecture of a specific Tcl shell. +.PP +This package allows the identification of the architecture of a +specific Tcl shell different from the shell running the package. The +only requirement is that the other shell (identified by its path), is +actually executable on the current machine. +.PP +While for most platform this means that the architecture of the +interogated shell is identical to the architecture of the running +shell this is not generally true. A counter example are all platforms +which have 32 and 64 bit variants and where a 64bit system is able to +run 32bit code. For these running and interogated shell may have +different 32/64 bit settings and thus different identifiers. +.PP +For applications like a code repository it is important to identify +the architecture of the shell which will actually run the installed +packages, versus the architecture of the shell running the repository +software. +.SH COMMANDS +.TP +\fBplatform::shell::identify \fIshell\fR +This command does the same identification as \fplatform::identify\fR, +for the specified Tcl shell, in contrast to the running shell. +.TP +\fBplatform::shell::generic \fIshell\fR +This command does the same identification as \fplatform::generic\fR, +for the specified Tcl shell, in contrast to the running shell. +.TP +\fBplatform::shell::platform \fIshell\fR +This command returns the contents of \fBtcl_platform(platform)\fR for +the specified Tcl shell. +.SH KEYWORDS +operating system, cpu architecture, platform, architecture |