llvm.org GIT mirror llvm / d8f4c8e
Abbreviate the long descriptions which are now in docs/SystemLibrary.html. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@16111 91177308-0d34-0410-b5e6-96231b3b80d8 Reid Spencer 16 years ago
1 changed file(s) with 23 addition(s) and 76 deletion(s). Raw diff Collapse all Expand all
88 The software located here, of necessity, has very specific and stringent design
99 rules. Violation of these rules means that cracks in the shield could form and
1010 the primary goal of the library is defeated. By consistently using this library,
11 LLVM becomes more easily ported to new platforms since (hopefully) the only thing
12 requiring porting is this library.
11 LLVM becomes more easily ported to new platforms since the only thing requiring
12 porting is this library.
1414 Complete documentation for the library can be found in the file:
1515 llvm/docs/SystemLibrary.html
1616 or at this URL:
1717 http://llvm.org/docs/SystemLibrary.html
19 However, for the impatient, here's a high level summary of the design rules:
19 While we recommend that you read the more detailed documentation, for the
20 impatient, here's a high level summary of the library's requirements.
21 1. No functions are declared with throw specifications. This is on purpose to
22 make sure that additional exception handling code is not introduced by the
23 compiler.
22 1. No system header files are to be exposed through the interface.
23 2. Std C++ and Std C header files are okay to be exposed through the interface.
24 3. No exposed system-specific functions.
25 4. No exposed system-specific data.
26 5. Data in lib/System classes must use only simple C++ intrinsic types.
27 6. Errors are handled by throwing std::string *only*.
28 7. Library must not throw any exceptions except std::string.
29 8. Interface functions must not have throw() specifications.
30 9. No duplicate function impementations are permitted within an operating
31 system class.
25 2. On error only an instance of std::string that explains the error and possibly
26 the context of the error may be thrown.
33 To accomplish these requirements, the library has numerous design criteria that
34 must be satisfied. Here's a high level summary of the library's design criteria:
28 3. Error messages should do whatever is necessary to get a readable message from
29 the operating system about the error. For example, on UNIX the strerror_r
30 function ought to be used.
32 4. Entry points into the library should be fairly high level and aimed at
33 completing some task needed by LLVM. There should *not* be a 1-to-1
34 relationship between operating system calls and the library's interface.
35 Certain implementations of the
37 5. The implementation of an lib/System interface can vary drastically between
38 platforms. That's okay as long as the end result of the interface function is
39 the same. For example, a function to create a directory is pretty straight
40 forward on all operating system. System V IPC on the other hand isn't even
41 supported on all platforms. Instead of "supporting" System V IPC, lib/System
42 should provide an interface to the basic concept of inter-process
43 communications. The implementations might use System V IPC if that was
44 available or named pipes, or whatever gets the job done effectively for a
45 given operating system.
47 6. Implementations are separated first by the general class of operating system
48 as provided by the configure script's $build variable. This variable is used
49 to create a link from $BUILD_OBJ_ROOT/lib/System/platform to a directory in
50 $BUILD_SRC_ROOT/lib/System directory with the same name as the $build
51 variable. This provides a retargetable include mechanism. By using the link's
52 name (platform) we can actually include the operating specific
53 implementation. For example, support $build is "Darwin" for MacOS X. If we
54 place:
55 #include "platform/File.cpp"
56 into a a file in lib/System, it will actually include
57 lib/System/Darwin/File.cpp. What this does is quickly differentiate the basic
58 class of operating system that will provide the implementation.
60 7. Implementation files in lib/System need may only do two things: (1) define
61 functions and data that is *TRULY* generic (completely platform agnostic) and
62 (2) #include the platform specific implementation with:
64 #include "platform/Impl.cpp"
66 where Impl is the name of the implementation files.
68 8. Platform specific implementation files (platform/Impl.cpp) may only #include
69 other Impl.cpp files found in directories under lib/System. The order of
70 inclusion is very important (from most generic to most specific) so that we
71 don't inadvertently place an implementation in the wrong place. For example,
72 consider a fictitious implementation file named DoIt.cpp. Here's how the
73 #includes should work for a Linux platform
75 lib/System/DoIt.cpp
76 #include "platform/DoIt.cpp" // platform specific impl. of Doit
77 DoIt
79 lib/System/Linux/DoIt.cpp // impl that works on all Linux
80 #include "../Unix/DoIt.cpp" // generic Unix impl. of DoIt
81 #include "../Unix/SUS/DoIt.cpp // SUS specific impl. of DoIt
82 #include "../Unix/SUS/v3/DoIt.cpp // SUSv3 specific impl. of DoIt
84 Note that the #includes in lib/System/Linux/DoIt.cpp are all optional but
85 should be used where the implementation of some functionality can be shared
86 across some set of Unix variants. We don't want to duplicate code across
87 variants if their implementation could be shared.
89 9. The library does not attempt to shield LLVM from the C++ standard library or
90 standard template library. These libraries are considered to be platform
91 agnostic already.
93 10. LLVM should not include *any* system headers anywhere except in lib/System.
95 11. lib/System must *not* expose *any* system headers through its interface.
36 1. No unused functionality (only what LLVM needs)
37 2. High-Level Interfaces
38 3. Use Opaque Classes
39 4. Common Implementations
40 5. Multiple Implementations
41 6. Minimize Memory Allocation
42 7. No Virtual Methods