[LLVMdev] The system library is gone for a long time.
Rafael Espíndola
rafael.espindola at gmail.com
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
More information about the llvm-dev
mailing list