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