diff options
Diffstat (limited to 'specs')
| -rw-r--r-- | specs/architecture-string.txt | 186 |
1 files changed, 186 insertions, 0 deletions
diff --git a/specs/architecture-string.txt b/specs/architecture-string.txt new file mode 100644 index 0000000..e8976fc --- /dev/null +++ b/specs/architecture-string.txt @@ -0,0 +1,186 @@ + Title: Architecture String Syntax + Status: DRAFT + Date: 2012-05-28 + + +1. Status of This Document +=========================== + +This specification is in `DRAFT` status. It is a work-in-progress and is +subject to change. Comments and revisions are welcome. + + +2. Abstract +============ + +This document defines binary architectures and application platforms and +describes the syntax of architecture strings in binary packages and package +archives. + + +3. Scope +========= + +This specification relates to architecture strings in binary packages and +package archives. A list of valid values for the `Architecture` field in source +packages is beyond the scope of this specification and is given in the most +recent "Source Package Format" specification. + + +4. Background +============== + +4.1 Binary Compatibility +------------------------- + +In a binary software distribution, package managers are designed to install +packages that are able to run on the host hardware and are compatible with other +packages already installed on the host operating system. "Binary compatibility" +is a general term that can be used to describe the ability of software to run on +particular hardware and work with other software. + +Disregarding interfaces between compiled userspace software packages (called +"application binary interfaces", or "ABIs"), there are several factors that can +affect binary compatibility of a set of software packages. These factors may +include the available microprocessor and coprocessor instruction set +architectures ("ISAs"), the word size used by the hardware, the byte order, the +kernel used in the operating system, the system libraries used in the operating +system, the procedure call standard ("PCS") used by the system libraries, and +the configuration of the system libraries. For example, a package compiled for +the ARMv7-A ISA won't run on an IA-32 computer. Similarly, a package compiled +for the Procedure Call Standard for the ARM Architecture ("AAPCS") may not work +with a package compiled for the ARM Procedure Call Standard ("APCS"). And a +package that is dynamically linked against uClibc can't be executed on a system +that uses EGLIBC. + +4.2 Application Platforms +-------------------------- + +It is useful for each vendor to be able to configure, for a particular use case, +at build time or at run time, many of the software packages in the operating +system they distribute to users. The hardware on which the operating system +runs and the set of configurations made for the use case can together be called +an "application platform". Packages configured and built for one application +platform can be considered incompatible with packages configured and built for +another application platform. + + +5. Rationale +============= + +By encoding infomation about the hardware, kernel, and system libraries into the +binary architecture string, ports to different hardware, kernels, and system +libraries are made easy and obvious. This can be seen as the natural +generalization and extension of Debian's architecture naming scheme, in which +non-Linux ports are identified by the kernel and hardware. + +Reusing the architecture string to identify application platforms enables the +use of existing package management technology to manage platform compatibility +between software packages. The opkg package manager can manage packages built +for a particular binary architecture and for a particular application platform. + +Architecture string components may not contain hypens because hypens are already +used to delimit components. Components may not contain underscores because +underscores are already used to separate package names, package versions, and +architecture strings in binary package file names. + + +6. Definitions +=============== + +Following are definitions for a number of terms used in this specification: + + * An "application platform" (or simply "platform") refers to a particular + binary architecture and a set of configurations made to adapt software + packages for a particular use case. + + * An "application platform string" is an architecture string that identifies a + particular application platform. + + * An "architecture string" is a string that identifies a particular binary + architecture or application platform. It may be used as a value for the + `Architecture` field of a binary package or in an index of binary packages + in a package archive, or it may be used in the file name of a binary package. + + * An "architecture string component" (or simply "component") is a substring of + an architecture string that contains a unit of information about the binary + architecture or application platform. + + * A "binary architecture" (or simply "architecture") is the set of values for + factors that may affect binary compatibility, including but not limited to: + instruction set architectures and their encodings, word size, byte order, + kernel, system libraries, and procedure call standard. + + * A "binary architecture string" is an architecture string that identifies a + particular binary architecture. + + * "Binary compatibility" is the ability of software to run on particular + hardware and to link against or usefully execute other software. + + +7. Syntax of the Architecture String +===================================== + +7.1 Architecture String Disambiguation +--------------------------------------- + +An architecture string may identify either a binary architecture or an +application platform. It is possible to determine if a particular architecture +string refers to a binary architecture or to an application platform by counting +the components it contains, as described in the following sections. + +7.2 Syntax of the Architecture String Component +------------------------------------------------ + +An architecture string component may only consist of lowercase Latin letters and +digits. See section 5 for more information. + +7.3 Syntax of the Binary Architecture String +--------------------------------------------- + +A binary architecture string contains information in three components, separated +by hyphens. Specifically, the syntax of a binary architecture string is: + + hardware-kernel-systemlibraries + +`hardware` is a string that briefly describes the hardware. Examples include +`cortexa8` to describe CPUs that implement the ARM Cortex-A8 core and `amd64` to +describe CPUs that implement either the AMD64 or Intel 64 ISAs. + +`kernel` is a string that briefly identifies the kernel. Examples include +`linux` to identify Linux-libre and `kfreebsd` to identify the kernel of the +FreeBSD operating system. + +`systemlibraries` is a string that briefly identifies the standard C and C++ +libraries. An example of this is `eglibc` to identify EGLIBC. + +7.4 Syntax of the Application Platform String +---------------------------------------------- + +An application platform string contains only one component, which names the +application platform. + + +8. Legal Notice +================ + +Copyright (C) 2012 Patrick "P. J." McDermott + +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be included +in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |