[llvm-commits] CVS: llvm/lib/System/README.txt

[Reid Spencer]

Changes in directory llvm/lib/System:

README.txt updated: 1.3 -> 1.4
---
Log message:

Abbreviate the long descriptions which are now in docs/SystemLibrary.html.


---
Diffs of the changes:  (+25 -78)

Index: llvm/lib/System/README.txt
diff -u llvm/lib/System/README.txt:1.3 llvm/lib/System/README.txt:1.4
--- llvm/lib/System/README.txt:1.3	Thu Aug 26 02:41:41 2004
+++ llvm/lib/System/README.txt	Sun Aug 29 21:03:51 2004
@@ -9,88 +9,35 @@
 The software located here, of necessity, has very specific and stringent design
 rules. Violation of these rules means that cracks in the shield could form and
 the primary goal of the library is defeated. By consistently using this library,
-LLVM becomes more easily ported to new platforms since (hopefully) the only thing
-requiring porting is this library.
+LLVM becomes more easily ported to new platforms since the only thing requiring 
+porting is this library.
 
 Complete documentation for the library can be found in the file:
   llvm/docs/SystemLibrary.html 
 or at this URL:
   http://llvm.org/docs/SystemLibrary.html
 
-However, for the impatient, here's a high level summary of the design rules:
+While we recommend that you read the more detailed documentation, for the 
+impatient, here's a high level summary of the library's requirements.
 
-1. No functions are declared with throw specifications. This is on purpose to 
-   make sure that additional exception handling code is not introduced by the
-   compiler.
-
-2. On error only an instance of std::string that explains the error and possibly
-   the context of the error may be thrown.
-
-3. Error messages should do whatever is necessary to get a readable message from
-   the operating system about the error. For example, on UNIX the strerror_r
-   function ought to be used.
-
-4. Entry points into the library should be fairly high level and aimed at
-   completing some task needed by LLVM. There should *not* be a 1-to-1
-   relationship between operating system calls and the library's interface.
-   Certain implementations of the
-
-5. The implementation of an lib/System 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 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.
-
-6. Implementations are separated first by the general class of operating system
-   as provided by the configure script's $build variable. This variable is used
-   to create a link from $BUILD_OBJ_ROOT/lib/System/platform to a directory in
-   $BUILD_SRC_ROOT/lib/System directory with the same name as the $build
-   variable. This provides a retargetable include mechanism. By using the link's
-   name (platform) we can actually include the operating specific
-   implementation. For example, support $build is "Darwin" for MacOS X. If we
-   place:
-     #include "platform/File.cpp"
-   into a a file in lib/System, it will actually include
-   lib/System/Darwin/File.cpp. What this does is quickly differentiate the basic
-   class of operating system that will provide the implementation.
-
-7. Implementation files in lib/System need may only do two things: (1) define 
-   functions and data that is *TRULY* generic (completely platform agnostic) and
-   (2) #include the platform specific implementation with:
-
-      #include "platform/Impl.cpp"
-
-   where Impl is the name of the implementation files.
-
-8. Platform specific implementation files (platform/Impl.cpp) may only #include
-   other Impl.cpp files found in directories under lib/System. The order of
-   inclusion is very important (from most generic to most specific) so that we
-   don't inadvertently place an implementation in the wrong place. For example,
-   consider a fictitious implementation file named DoIt.cpp. Here's how the
-   #includes should work for a Linux platform
-
-   lib/System/DoIt.cpp
-     #include "platform/DoIt.cpp"        // platform specific impl. of Doit
-     DoIt
-
-   lib/System/Linux/DoIt.cpp             // impl that works on all Linux 
-     #include "../Unix/DoIt.cpp"         // generic Unix impl. of DoIt
-     #include "../Unix/SUS/DoIt.cpp      // SUS specific impl. of DoIt
-     #include "../Unix/SUS/v3/DoIt.cpp   // SUSv3 specific impl. of DoIt
-
-   Note that the #includes in lib/System/Linux/DoIt.cpp are all optional but
-   should be used where the implementation of some functionality can be shared
-   across some set of Unix variants. We don't want to duplicate code across
-   variants if their implementation could be shared.
-
-9. The library does not attempt to shield LLVM from the C++ standard library or
-   standard template library. These libraries are considered to be platform
-   agnostic already.
-
-10. LLVM should not include *any* system headers anywhere except in lib/System.
-
-11. lib/System must *not* expose *any* system headers through its interface.
+ 1. No system header files are to be exposed through the interface.
+ 2. Std C++ and Std C header files are okay to be exposed through the interface.
+ 3. No exposed system-specific functions.
+ 4. No exposed system-specific data.
+ 5. Data in lib/System classes must use only simple C++ intrinsic types.
+ 6. Errors are handled by throwing std::string *only*.
+ 7. Library must not throw any exceptions except std::string.
+ 8. Interface functions must not have throw() specifications.
+ 9. No duplicate function impementations are permitted within an operating
+    system class.
+
+To accomplish these requirements, the library has numerous design criteria that 
+must be satisfied. Here's a high level summary of the library's design criteria:
+
+ 1. No unused functionality (only what LLVM needs)
+ 2. High-Level Interfaces
+ 3. Use Opaque Classes
+ 4. Common Implementations</a></li>
+ 5. Multiple Implementations</a></li>
+ 6. Minimize Memory Allocation</a></li>
+ 7. No Virtual Methods