llvm dev - May 2013 - [LLVMdev] The system library is gone for a long time.

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>

I think it is fine, but please wait for Sean to confirm.

On 27 May 2013 13:34, 罗勇刚(Yonggang Luo) <luoyonggang at gmail.com>
wrote:
> 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

On Mon, May 27, 2013 at 11:34 AM, 罗勇刚(Yonggang Luo)
<luoyonggang at gmail.com>wrote:
> ping,is there any other problems in this patch?
>
>
AFAIK, libSupport does more than what this document describes (for example,
it contains ADT, which are portable and not system-specific, contrary to
the second paragraph of the document). Does it make sense to just globally
replace "Support" for "System"? I wasn't around when the
transition was
made, so I don't know. Please get a confirmation from someone who can speak
authoritatively about the transition from libSystem to libSupport. Other
than that, LGTM.

Also, I would expect a follow-up patch for lib/Support/README.txt.system
after this patch has landed.

btw, in the future please attach the patch rather than including it
directly in the body of the message.

-- Sean Silva
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20130527/498c3823/attachment.html>

> AFAIK, libSupport does more than what this document describes (for example,
> it contains ADT, which are portable and not system-specific, contrary to
the
> second paragraph of the document). Does it make sense to just globally
> replace "Support" for "System"? I wasn't around
when the transition was
> made, so I don't know. Please get a confirmation from someone who can
speak
> authoritatively about the transition from libSystem to libSupport. Other
> than that, LGTM.
System got merged into Support a long time ago. We could improve the
documentation of what lib/Support is, but this is a good start IMHO.

Cheers,
Rafael