-However, for the impatient, here's a high level summary of the design rules:
-
-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.
+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 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 returning "true" and setting an optional std::string
+ 7. Library must not throw any exceptions, period.
+ 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