[LLVMdev] The system library is gone for a long time.

[罗勇刚(Yonggang Luo)]

ping,is there any other problems in this patch?
在 2013-5-27 上午12:09，"罗勇刚(Yonggang Luo)" <luoyonggang at gmail.com>写道：

> From 1d658dd52ca3973109e370103a7dd3485a4ee11f Mon Sep 17 00:00:00 2001
> From: Yonggang Luo <luoyonggang at gmail.com>
> Date: Mon, 27 May 2013 00:07:16 +0800
> Subject: [PATCH] The System library is merged into Support library.
>
> ---
>  docs/SystemLibrary.rst | 104
> ++++++++++++++++++++++++-------------------------
>  docs/index.rst         |   4 +-
>  2 files changed, 54 insertions(+), 54 deletions(-)
>
> diff --git a/docs/SystemLibrary.rst b/docs/SystemLibrary.rst
> index 0d0f4fa..4c6226c 100644
> --- a/docs/SystemLibrary.rst
> +++ b/docs/SystemLibrary.rst
> @@ -1,31 +1,31 @@
>  ==============
> -System Library
> +Support Library
>  ==============
>
>  Abstract
>  ========
>
> -This document provides some details on LLVM's System Library, located in
> the
> -source at ``lib/System`` and ``include/llvm/System``. The library's
> purpose is
> +This document provides some details on LLVM's Support Library, located in
> the
> +source at ``lib/Support`` and ``include/llvm/Support``. The library's
> purpose is
>  to shield LLVM from the differences between operating systems for the few
>  services LLVM needs from the operating system. Much of LLVM is written
> using
>  portability features of standard C++. However, in a few areas, system
> dependent
> -facilities are needed and the System Library is the wrapper around those
> system
> +facilities are needed and the Support Library is the wrapper around
> those system
>  calls.
>
>  By centralizing LLVM's use of operating system interfaces, we make it
> possible
>  for the LLVM tool chain and runtime libraries to be more easily ported to
> new
> -platforms since (theoretically) only ``lib/System`` needs to be ported.
>  This
> +platforms since (theoretically) only ``lib/Support`` needs to be ported.
>  This
>  library also unclutters the rest of LLVM from #ifdef use and special
> cases for
>  specific operating systems. Such uses are replaced with simple calls to
> the
> -interfaces provided in ``include/llvm/System``.
> +interfaces provided in ``include/llvm/Support``.
>
> -Note that the System Library is not intended to be a complete operating
> system
> +Note that the Support Library is not intended to be a complete operating
> system
>  wrapper (such as the Adaptive Communications Environment (ACE) or Apache
>  Portable Runtime (APR)), but only provides the functionality necessary to
>  support LLVM.
>
> -The System Library was written by Reid Spencer who formulated the design
> based
> +The Support Library was written by Reid Spencer who formulated the design
> based
>  on similar work originating from the eXtensible Programming System (XPS).
>  Several people helped with the effort; especially, Jeff Cohen and Henrik
> Bach
>  on the Win32 port.
> @@ -34,56 +34,56 @@ Keeping LLVM Portable
>  =====================
>
>  In order to keep LLVM portable, LLVM developers should adhere to a set of
> -portability rules associated with the System Library. Adherence to these
> rules
> -should help the System Library achieve its goal of shielding LLVM from the
> +portability rules associated with the Support Library. Adherence to these
> rules
> +should help the Support Library achieve its goal of shielding LLVM from
> the
>  variations in operating system interfaces and doing so efficiently.  The
>  following sections define the rules needed to fulfill this objective.
>
> -Don't Include System Headers
> +Don't Include Support Headers
>  ----------------------------
>
> -Except in ``lib/System``, no LLVM source code should directly
> ``#include`` a
> +Except in ``lib/Support``, no LLVM source code should directly
> ``#include`` a
>  system header. Care has been taken to remove all such ``#includes`` from
> LLVM
> -while ``lib/System`` was being developed.  Specifically this means that
> header
> +while ``lib/Support`` was being developed.  Specifically this means that
> header
>  files like "``unistd.h``", "``windows.h``", "``stdio.h``", and
> "``string.h``"
>  are forbidden to be included by LLVM source code outside the
> implementation of
> -``lib/System``.
> +``lib/Support``.
>
>  To obtain system-dependent functionality, existing interfaces to the
> system
> -found in ``include/llvm/System`` should be used. If an appropriate
> interface is
> -not available, it should be added to ``include/llvm/System`` and
> implemented in
> -``lib/System`` for all supported platforms.
> +found in ``include/llvm/Support`` should be used. If an appropriate
> interface is
> +not available, it should be added to ``include/llvm/Support`` and
> implemented in
> +``lib/Support`` for all supported platforms.
>
> -Don't Expose System Headers
> +Don't Expose Support Headers
>  ---------------------------
>
> -The System Library must shield LLVM from **all** system headers. To obtain
> -system level functionality, LLVM source must ``#include
> "llvm/System/Thing.h"``
> +The Support Library must shield LLVM from **all** system headers. To
> obtain
> +system level functionality, LLVM source must ``#include
> "llvm/Support/Thing.h"``
>  and nothing else. This means that ``Thing.h`` cannot expose any system
> header
>  files. This protects LLVM from accidentally using system specific
> functionality
> -and only allows it via the ``lib/System`` interface.
> +and only allows it via the ``lib/Support`` interface.
>
>  Use Standard C Headers
>  ----------------------
>
>  The **standard** C headers (the ones beginning with "c") are allowed to be
> -exposed through the ``lib/System`` interface. These headers and the
> things they
> +exposed through the ``lib/Support`` interface. These headers and the
> things they
>  declare are considered to be platform agnostic. LLVM source files may
> include
> -them directly or obtain their inclusion through ``lib/System`` interfaces.
> +them directly or obtain their inclusion through ``lib/Support``
> interfaces.
>
>  Use Standard C++ Headers
>  ------------------------
>
>  The **standard** C++ headers from the standard C++ library and standard
> -template library may be exposed through the ``lib/System`` interface.
> These
> +template library may be exposed through the ``lib/Support`` interface.
> These
>  headers and the things they declare are considered to be platform
> agnostic.
>  LLVM source files may include them or obtain their inclusion through
> -``lib/System`` interfaces.
> +``lib/Support`` interfaces.
>
>  High Level Interface
>  --------------------
>
> -The entry points specified in the interface of ``lib/System`` must be
> aimed at
> +The entry points specified in the interface of ``lib/Support`` must be
> aimed at
>  completing some reasonably high level task needed by LLVM. We do not want
> to
>  simply wrap each operating system call. It would be preferable to wrap
> several
>  operating system calls that are always used in conjunction with one
> another by
> @@ -92,21 +92,21 @@ LLVM.
>  For example, consider what is needed to execute a program, wait for it to
>  complete, and return its result code. On Unix, this involves the following
>  operating system calls: ``getenv``, ``fork``, ``execve``, and ``wait``.
> The
> -correct thing for ``lib/System`` to provide is a function, say
> +correct thing for ``lib/Support`` to provide is a function, say
>  ``ExecuteProgramAndWait``, that implements the functionality completely.
>  what
>  we don't want is wrappers for the operating system calls involved.
>
>  There must **not** be a one-to-one relationship between operating system
> -calls and the System library's interface. Any such interface function
> will be
> +calls and the Support library's interface. Any such interface function
> will be
>  suspicious.
>
>  No Unused Functionality
>  -----------------------
>
> -There must be no functionality specified in the interface of
> ``lib/System``
> +There must be no functionality specified in the interface of
> ``lib/Support``
>  that isn't actually used by LLVM. We're not writing a general purpose
> operating
>  system wrapper here, just enough to satisfy LLVM's needs. And, LLVM
> doesn't
> -need much. This design goal aims to keep the ``lib/System`` interface
> small and
> +need much. This design goal aims to keep the ``lib/Support``
> interface small and
>  understandable which should foster its actual use and adoption.
>
>  No Duplicate Implementations
> @@ -121,7 +121,7 @@ systems supported for a given class of operating
> system (e.g. Unix, Win32).
>  No Virtual Methods
>  ------------------
>
> -The System Library interfaces can be called quite frequently by LLVM. In
> order
> +The Support Library interfaces can be called quite frequently by LLVM. In
> order
>  to make those calls as efficient as possible, we discourage the use of
> virtual
>  methods. There is no need to use inheritance for implementation
> differences, it
>  just adds complexity. The ``#include`` mechanism works just fine.
> @@ -129,24 +129,24 @@ just adds complexity. The ``#include`` mechanism
> works just fine.
>  No Exposed Functions
>  --------------------
>
> -Any functions defined by system libraries (i.e. not defined by
> ``lib/System``)
> -must not be exposed through the ``lib/System`` interface, even if the
> header
> +Any functions defined by system libraries (i.e. not defined by
> ``lib/Support``)
> +must not be exposed through the ``lib/Support`` interface, even if the
> header
>  file for that function is not exposed. This prevents inadvertent use of
> system
>  specific functionality.
>
>  For example, the ``stat`` system call is notorious for having variations
> in the
> -data it provides. ``lib/System`` must not declare ``stat`` nor allow it
> to be
> +data it provides. ``lib/Support`` must not declare ``stat`` nor allow it
> to be
>  declared. Instead it should provide its own interface to discovering
>  information about files and directories. Those interfaces may be
> implemented in
>  terms of ``stat`` but that is strictly an implementation detail. The
> interface
> -provided by the System Library must be implemented on all platforms (even
> those
> +provided by the Support Library must be implemented on all platforms
> (even those
>  without ``stat``).
>
>  No Exposed Data
>  ---------------
>
> -Any data defined by system libraries (i.e. not defined by ``lib/System``)
> must
> -not be exposed through the ``lib/System`` interface, even if the header
> file
> +Any data defined by system libraries (i.e. not defined by
> ``lib/Support``) must
> +not be exposed through the ``lib/Support`` interface, even if the header
> file
>  for that function is not exposed. As with functions, this prevents
> inadvertent
>  use of data that might not exist on all platforms.
>
> @@ -161,7 +161,7 @@ privileges", etc. while other errors are much
> harder like "out of space", "bad
>  disk sector", or "system call interrupted". We'll call the first group
> "*soft*"
>  errors and the second group "*hard*" errors.
>
> -``lib/System`` must always attempt to minimize soft errors.  This is a
> design
> +``lib/Support`` must always attempt to minimize soft errors.  This is a
> design
>  requirement because the minimization of soft errors can affect the
> granularity
>  and the nature of the interface. In general, if you find that you're
> wanting to
>  throw soft errors, you must review the granularity of the interface
> because it
> @@ -171,13 +171,13 @@ faced with hard errors.
>
>  For a trivial example, suppose we wanted to add an
> "``OpenFileForWriting``"
>  function. For many operating systems, if the file doesn't exist,
> attempting to
> -open the file will produce an error.  However, ``lib/System`` should not
> simply
> +open the file will produce an error.  However, ``lib/Support`` should
> not simply
>  throw that error if it occurs because its a soft error. The problem is
> that the
>  interface function, ``OpenFileForWriting`` is too low level. It should be
>  ``OpenOrCreateFileForWriting``. In the case of the soft "doesn't exist"
> error,
>  this function would just create it and then open it for writing.
>
> -This design principle needs to be maintained in ``lib/System`` because it
> +This design principle needs to be maintained in ``lib/Support`` because it
>  avoids the propagation of soft error handling throughout the rest of LLVM.
>  Hard errors will generally just cause a termination for an LLVM tool so
> don't
>  be bashful about throwing them.
> @@ -194,10 +194,10 @@ Rules of thumb:
>  No throw Specifications
>  -----------------------
>
> -None of the ``lib/System`` interface functions may be declared with C++
> +None of the ``lib/Support`` interface functions may be declared with C++
>  ``throw()`` specifications on them. This requirement makes sure that the
>  compiler does not insert additional exception handling code into the
> interface
> -functions. This is a performance consideration: ``lib/System`` functions
> are at
> +functions. This is a performance consideration: ``lib/Support``
> functions are at
>  the bottom of many call chains and as such can be frequently called. We
> need
>  them to be as efficient as possible.  However, no routines in the system
>  library should actually throw exceptions.
> @@ -205,28 +205,28 @@ library should actually throw exceptions.
>  Code Organization
>  -----------------
>
> -Implementations of the System Library interface are separated by their
> general
> +Implementations of the Support Library interface are separated by their
> general
>  class of operating system. Currently only Unix and Win32 classes are
> defined
>  but more could be added for other operating system classifications.  To
> -distinguish which implementation to compile, the code in ``lib/System``
> uses
> +distinguish which implementation to compile, the code in ``lib/Support``
> uses
>  the ``LLVM_ON_UNIX`` and ``LLVM_ON_WIN32`` ``#defines`` provided via
> configure
> -through the ``llvm/Config/config.h`` file. Each source file in
> ``lib/System``,
> +through the ``llvm/Config/config.h`` file. Each source file in
> ``lib/Support``,
>  after implementing the generic (operating system independent)
> functionality
>  needs to include the correct implementation using a set of
>  ``#if defined(LLVM_ON_XYZ)`` directives. For example, if we had
> -``lib/System/File.cpp``, we'd expect to see in that file:
> +``lib/Support/Path.cpp``, we'd expect to see in that file:
>
>  .. code-block:: c++
>
>    #if defined(LLVM_ON_UNIX)
> -  #include "Unix/File.cpp"
> +  #include "Unix/Path.inc"
>    #endif
>    #if defined(LLVM_ON_WIN32)
> -  #include "Win32/File.cpp"
> +  #include "Windows/Path.inc"
>    #endif
>
> -The implementation in ``lib/System/Unix/File.cpp`` should handle all Unix
> -variants. The implementation in ``lib/System/Win32/File.cpp`` should
> handle all
> +The implementation in ``lib/Support/Unix/Path.inc`` should handle all Unix
> +variants. The implementation in ``lib/Support/Windows/Path.inc``
> should handle all
>  Win32 variants.  What this does is quickly differentiate the basic class
> of
>  operating system that will provide the implementation. The specific
> details for
>  a given platform must still be determined through the use of ``#ifdef``.
> @@ -234,12 +234,12 @@ a given platform must still be determined
> through the use of ``#ifdef``.
>  Consistent Semantics
>  --------------------
>
> -The implementation of a ``lib/System`` interface can vary drastically
> between
> +The implementation of a ``lib/Support`` interface can vary drastically
> between
>  platforms. That's okay as long as the end result of the interface
> function is
>  the same. For example, a function to create a directory is pretty straight
>  forward on all operating system. System V IPC on the other hand isn't even
>  supported on all platforms. Instead of "supporting" System V IPC,
> -``lib/System`` should provide an interface to the basic concept of
> +``lib/Support`` should provide an interface to the basic concept of
>  inter-process communications. The implementations might use System V IPC
> if
>  that was available or named pipes, or whatever gets the job done
> effectively
>  for a given operating system.  In all cases, the interface and the
> diff --git a/docs/index.rst b/docs/index.rst
> index 6b182da..28107d7 100644
> --- a/docs/index.rst
> +++ b/docs/index.rst
> @@ -271,8 +271,8 @@ For API clients and LLVM developers.
>  :doc:`BitCodeFormat`
>     This describes the file format and encoding used for LLVM "bc" files.
>
> -:doc:`System Library <SystemLibrary>`
> -   This document describes the LLVM System Library (``lib/System``) and
> +:doc:`Support Library <SystemLibrary>`
> +   This document describes the LLVM Support Library (``lib/Support``) and
>     how to keep LLVM source code portable
>
>  :doc:`LinkTimeOptimization`
> --
> 1.8.1.msysgit.1
>
> 2013/5/26 Rafael Espíndola <rafael.espindola at gmail.com>:
> > On 25 May 2013 15:30, Sean Silva <silvas at purdue.edu> wrote:
> >> This will break existing URLs. Until we have a way to set up redirects
> the
> >> file name should stay the same.
> >
> > Would a SystemLibrary.rst saying it was replaced with the support
> library be ok?
> >
> >> -- Sean Silva
> >
> > Cheers,
> > Rafael
>
>
>
> --
>          此致
> 礼
> 罗勇刚
> Yours
>     sincerely,
> Yonggang Luo
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20130528/0fd74761/attachment.html>