Write "Architecture String Syntax" specification.

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.