summaryrefslogtreecommitdiffstats
path: root/specs
diff options
context:
space:
mode:
authorP. J. McDermott <pjm@nac.net>2012-05-28 22:00:03 (EDT)
committer P. J. McDermott <pjm@nac.net>2012-05-28 22:00:03 (EDT)
commite0ab98c4f7b25e49c96487dd3ca4ffbca46cbe7c (patch)
tree17961112f922be8965d7dff9735148fe94c1dd6b /specs
parent52e49b463d58ce788b7bff5cb1d8f746d1fc1399 (diff)
Write "Architecture String Syntax" specification.
Diffstat (limited to 'specs')
-rw-r--r--specs/architecture-string.txt186
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.