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

Mon May 27 11:38:37 PDT 2013

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