.. highlight:: none


.. index::
   pair: library interface; design

.. _design-lib:


Library interface
=================

.. mps:prefix:: design.mps.lib


Introduction
------------

:mps:tag:`intro` This document is the design of the MPS Library Interface, a
part of the plinth.

:mps:tag:`readership` Any MPS developer. Any clients that are prepared to
read this in order to get documentation.


Goals
-----

:mps:tag:`goal` The goals of the MPS library interface are:

:mps:tag:`goal.host` To control the dependency of the MPS on the hosted ISO
C library so that the core MPS remains freestanding (see
design.mps.exec-env_).

.. _design.mps.exec-env: exec-env.html

:mps:tag:`goal.free` To allow the core MPS convenient access to ISO C
functionality that is provided on freestanding platforms (see
design.mps.exec-env_).


Description
-----------

Overview
........

:mps:tag:`overview.access` The core MPS needs to access functionality that
could be provided by an ISO C hosted environment.

:mps:tag:`overview.hosted` The core MPS must not make direct use of any
facilities in the hosted environment (design.mps.exec-env_). However,
it is sensible to make use of them when the MPS is deployed in a
hosted environment.

:mps:tag:`overview.hosted.indirect` The core MPS does not make any direct
use of hosted ISO C library facilities. Instead, it indirects through
the MPS Library Interface, impl.h.mpslib.

:mps:tag:`overview.provision.client` In a freestanding environment the
client is expected to provide functions meeting this interface to the
MPS.

:mps:tag:`overview.provision.hosted` In a hosted environment,
impl.c.mpsliban may be used. It just maps impl.h.mpslib directly onto
the ISO C library equivalents.


Implementation
--------------

:mps:tag:`impl` The MPS Library Interface comprises a header file
impl.h.mpslib and some documentation.

:mps:tag:`impl.decl` The header file defines the interface to definitions
which parallel those parts of the non-freestanding ISO headers which
are used by the MPS.

:mps:tag:`impl.include` The header file also includes the freestanding
header ``<stddef.h>``.