llvm.org GIT mirror llvm / cd4dcda
[Docs] [Support] System Library to Support Library transition along with minor corrections to reflect it. System Library has been a long deprecated term along with the path lib/System, having been superseded/renamed to the Support Library a long time ago. These patches reflect those changes in documentation as well as update some outdated examples and provide context to the origin of the Support Library. Differential Revision: https://reviews.llvm.org/D52107 git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@342500 91177308-0d34-0410-b5e6-96231b3b80d8 Kristina Brooks 11 months ago
3 changed file(s) with 252 addition(s) and 243 deletion(s). Raw diff Collapse all Expand all
0 ===============
1 Support Library
2 ===============
3
4 Abstract
5 ========
6
7 This document provides some details on LLVM's Support Library, located in the
8 source at ``lib/Support`` and ``include/llvm/Support``. The library's purpose
9 is to shield LLVM from the differences between operating systems for the few
10 services LLVM needs from the operating system. Much of LLVM is written using
11 portability features of standard C++. However, in a few areas, system dependent
12 facilities are needed and the Support Library is the wrapper around those
13 system calls.
14
15 By centralizing LLVM's use of operating system interfaces, we make it possible
16 for the LLVM tool chain and runtime libraries to be more easily ported to new
17 platforms since (theoretically) only ``lib/Support`` needs to be ported. This
18 library also unclutters the rest of LLVM from #ifdef use and special cases for
19 specific operating systems. Such uses are replaced with simple calls to the
20 interfaces provided in ``include/llvm/Support``.
21
22 Note that the Support Library is not intended to be a complete operating system
23 wrapper (such as the Adaptive Communications Environment (ACE) or Apache
24 Portable Runtime (APR)), but only provides the functionality necessary to
25 support LLVM.
26
27 The Support Library was originally referred to as the System Library, written
28 by Reid Spencer who formulated the design based on similar work originating
29 from the eXtensible Programming System (XPS). Several people helped with the
30 effort; especially, Jeff Cohen and Henrik Bach on the Win32 port.
31
32 Keeping LLVM Portable
33 =====================
34
35 In order to keep LLVM portable, LLVM developers should adhere to a set of
36 portability rules associated with the Support Library. Adherence to these rules
37 should help the Support Library achieve its goal of shielding LLVM from the
38 variations in operating system interfaces and doing so efficiently. The
39 following sections define the rules needed to fulfill this objective.
40
41 Don't Include System Headers
42 ----------------------------
43
44 Except in ``lib/Support``, no LLVM source code should directly ``#include`` a
45 system header. Care has been taken to remove all such ``#includes`` from LLVM
46 while ``lib/Support`` was being developed. Specifically this means that header
47 files like "``unistd.h``", "``windows.h``", "``stdio.h``", and "``string.h``"
48 are forbidden to be included by LLVM source code outside the implementation of
49 ``lib/Support``.
50
51 To obtain system-dependent functionality, existing interfaces to the system
52 found in ``include/llvm/Support`` should be used. If an appropriate interface is
53 not available, it should be added to ``include/llvm/Support`` and implemented in
54 ``lib/Support`` for all supported platforms.
55
56 Don't Expose System Headers
57 ---------------------------
58
59 The Support Library must shield LLVM from **all** system headers. To obtain
60 system level functionality, LLVM source must ``#include "llvm/System/Thing.h"``
61 and nothing else. This means that ``Thing.h`` cannot expose any system header
62 files. This protects LLVM from accidentally using system specific functionality
63 and only allows it via the ``lib/Support`` interface.
64
65 Use Standard C Headers
66 ----------------------
67
68 The **standard** C headers (the ones beginning with "c") are allowed to be
69 exposed through the ``lib/Support`` interface. These headers and the things they
70 declare are considered to be platform agnostic. LLVM source files may include
71 them directly or obtain their inclusion through ``lib/Support`` interfaces.
72
73 Use Standard C++ Headers
74 ------------------------
75
76 The **standard** C++ headers from the standard C++ library and standard
77 template library may be exposed through the ``lib/Support`` interface. These
78 headers and the things they declare are considered to be platform agnostic.
79 LLVM source files may include them or obtain their inclusion through
80 ``lib/Support`` interfaces.
81
82 High Level Interface
83 --------------------
84
85 The entry points specified in the interface of ``lib/Support`` must be aimed at
86 completing some reasonably high level task needed by LLVM. We do not want to
87 simply wrap each operating system call. It would be preferable to wrap several
88 operating system calls that are always used in conjunction with one another by
89 LLVM.
90
91 For example, consider what is needed to execute a program, wait for it to
92 complete, and return its result code. On Unix, this involves the following
93 operating system calls: ``getenv``, ``fork``, ``execve``, and ``wait``. The
94 correct thing for ``lib/Support`` to provide is a function, say
95 ``ExecuteProgramAndWait``, that implements the functionality completely. what
96 we don't want is wrappers for the operating system calls involved.
97
98 There must **not** be a one-to-one relationship between operating system
99 calls and the Support library's interface. Any such interface function will be
100 suspicious.
101
102 No Unused Functionality
103 -----------------------
104
105 There must be no functionality specified in the interface of ``lib/Support``
106 that isn't actually used by LLVM. We're not writing a general purpose operating
107 system wrapper here, just enough to satisfy LLVM's needs. And, LLVM doesn't
108 need much. This design goal aims to keep the ``lib/Support`` interface small and
109 understandable which should foster its actual use and adoption.
110
111 No Duplicate Implementations
112 ----------------------------
113
114 The implementation of a function for a given platform must be written exactly
115 once. This implies that it must be possible to apply a function's
116 implementation to multiple operating systems if those operating systems can
117 share the same implementation. This rule applies to the set of operating
118 systems supported for a given class of operating system (e.g. Unix, Win32).
119
120 No Virtual Methods
121 ------------------
122
123 The Support Library interfaces can be called quite frequently by LLVM. In order
124 to make those calls as efficient as possible, we discourage the use of virtual
125 methods. There is no need to use inheritance for implementation differences, it
126 just adds complexity. The ``#include`` mechanism works just fine.
127
128 No Exposed Functions
129 --------------------
130
131 Any functions defined by system libraries (i.e. not defined by ``lib/Support``)
132 must not be exposed through the ``lib/Support`` interface, even if the header
133 file for that function is not exposed. This prevents inadvertent use of system
134 specific functionality.
135
136 For example, the ``stat`` system call is notorious for having variations in the
137 data it provides. ``lib/Support`` must not declare ``stat`` nor allow it to be
138 declared. Instead it should provide its own interface to discovering
139 information about files and directories. Those interfaces may be implemented in
140 terms of ``stat`` but that is strictly an implementation detail. The interface
141 provided by the Support Library must be implemented on all platforms (even
142 those without ``stat``).
143
144 No Exposed Data
145 ---------------
146
147 Any data defined by system libraries (i.e. not defined by ``lib/Support``) must
148 not be exposed through the ``lib/Support`` interface, even if the header file
149 for that function is not exposed. As with functions, this prevents inadvertent
150 use of data that might not exist on all platforms.
151
152 Minimize Soft Errors
153 --------------------
154
155 Operating system interfaces will generally provide error results for every
156 little thing that could go wrong. In almost all cases, you can divide these
157 error results into two groups: normal/good/soft and abnormal/bad/hard. That is,
158 some of the errors are simply information like "file not found", "insufficient
159 privileges", etc. while other errors are much harder like "out of space", "bad
160 disk sector", or "system call interrupted". We'll call the first group "*soft*"
161 errors and the second group "*hard*" errors.
162
163 ``lib/Support`` must always attempt to minimize soft errors. This is a design
164 requirement because the minimization of soft errors can affect the granularity
165 and the nature of the interface. In general, if you find that you're wanting to
166 throw soft errors, you must review the granularity of the interface because it
167 is likely you're trying to implement something that is too low level. The rule
168 of thumb is to provide interface functions that **can't** fail, except when
169 faced with hard errors.
170
171 For a trivial example, suppose we wanted to add an "``OpenFileForWriting``"
172 function. For many operating systems, if the file doesn't exist, attempting to
173 open the file will produce an error. However, ``lib/Support`` should not simply
174 throw that error if it occurs because its a soft error. The problem is that the
175 interface function, ``OpenFileForWriting`` is too low level. It should be
176 ``OpenOrCreateFileForWriting``. In the case of the soft "doesn't exist" error,
177 this function would just create it and then open it for writing.
178
179 This design principle needs to be maintained in ``lib/Support`` because it
180 avoids the propagation of soft error handling throughout the rest of LLVM.
181 Hard errors will generally just cause a termination for an LLVM tool so don't
182 be bashful about throwing them.
183
184 Rules of thumb:
185
186 #. Don't throw soft errors, only hard errors.
187
188 #. If you're tempted to throw a soft error, re-think the interface.
189
190 #. Handle internally the most common normal/good/soft error conditions
191 so the rest of LLVM doesn't have to.
192
193 No throw Specifications
194 -----------------------
195
196 None of the ``lib/Support`` interface functions may be declared with C++
197 ``throw()`` specifications on them. This requirement makes sure that the
198 compiler does not insert additional exception handling code into the interface
199 functions. This is a performance consideration: ``lib/Support`` functions are
200 at the bottom of many call chains and as such can be frequently called. We
201 need them to be as efficient as possible. However, no routines in the system
202 library should actually throw exceptions.
203
204 Code Organization
205 -----------------
206
207 Implementations of the Support Library interface are separated by their general
208 class of operating system. Currently only Unix and Win32 classes are defined
209 but more could be added for other operating system classifications. To
210 distinguish which implementation to compile, the code in ``lib/Support`` uses
211 the ``LLVM_ON_UNIX`` and ``_WIN32`` ``#defines``. Each source file in
212 ``lib/Support``, after implementing the generic (operating system independent)
213 functionality needs to include the correct implementation using a set of
214 ``#if defined(LLVM_ON_XYZ)`` directives. For example, if we had
215 ``lib/Support/File.cpp``, we'd expect to see in that file:
216
217 .. code-block:: c++
218
219 #if defined(LLVM_ON_UNIX)
220 #include "Unix/File.inc"
221 #endif
222 #if defined(_WIN32)
223 #include "Windows/File.inc"
224 #endif
225
226 The implementation in ``lib/Support/Unix/File.cpp`` should handle all Unix
227 variants. The implementation in ``lib/Support/Windows/File.cpp`` should handle
228 all Windows variants. What this does is quickly differentiate the basic class
229 of operating system that will provide the implementation. The specific details
230 for a given platform must still be determined through the use of ``#ifdef``.
231
232 Consistent Semantics
233 --------------------
234
235 The implementation of a ``lib/Support`` interface can vary drastically between
236 platforms. That's okay as long as the end result of the interface function is
237 the same. For example, a function to create a directory is pretty straight
238 forward on all operating system. System V IPC on the other hand isn't even
239 supported on all platforms. Instead of "supporting" System V IPC,
240 ``lib/Support`` should provide an interface to the basic concept of
241 inter-process communications. The implementations might use System V IPC if
242 that was available or named pipes, or whatever gets the job done effectively
243 for a given operating system. In all cases, the interface and the
244 implementation must be semantically consistent.
11 System Library
22 ==============
33
4 Abstract
5 ========
4 Moved
5 =====
66
7 This document provides some details on LLVM's System Library, located in the
8 source at ``lib/System`` and ``include/llvm/System``. The library's purpose is
9 to shield LLVM from the differences between operating systems for the few
10 services LLVM needs from the operating system. Much of LLVM is written using
11 portability features of standard C++. However, in a few areas, system dependent
12 facilities are needed and the System Library is the wrapper around those system
13 calls.
14
15 By centralizing LLVM's use of operating system interfaces, we make it possible
16 for the LLVM tool chain and runtime libraries to be more easily ported to new
17 platforms since (theoretically) only ``lib/System`` needs to be ported. This
18 library also unclutters the rest of LLVM from #ifdef use and special cases for
19 specific operating systems. Such uses are replaced with simple calls to the
20 interfaces provided in ``include/llvm/System``.
21
22 Note that the System Library is not intended to be a complete operating system
23 wrapper (such as the Adaptive Communications Environment (ACE) or Apache
24 Portable Runtime (APR)), but only provides the functionality necessary to
25 support LLVM.
26
27 The System Library was written by Reid Spencer who formulated the design based
28 on similar work originating from the eXtensible Programming System (XPS).
29 Several people helped with the effort; especially, Jeff Cohen and Henrik Bach
30 on the Win32 port.
31
32 Keeping LLVM Portable
33 =====================
34
35 In order to keep LLVM portable, LLVM developers should adhere to a set of
36 portability rules associated with the System Library. Adherence to these rules
37 should help the System Library achieve its goal of shielding LLVM from the
38 variations in operating system interfaces and doing so efficiently. The
39 following sections define the rules needed to fulfill this objective.
40
41 Don't Include System Headers
42 ----------------------------
43
44 Except in ``lib/System``, no LLVM source code should directly ``#include`` a
45 system header. Care has been taken to remove all such ``#includes`` from LLVM
46 while ``lib/System`` was being developed. Specifically this means that header
47 files like "``unistd.h``", "``windows.h``", "``stdio.h``", and "``string.h``"
48 are forbidden to be included by LLVM source code outside the implementation of
49 ``lib/System``.
50
51 To obtain system-dependent functionality, existing interfaces to the system
52 found in ``include/llvm/System`` should be used. If an appropriate interface is
53 not available, it should be added to ``include/llvm/System`` and implemented in
54 ``lib/System`` for all supported platforms.
55
56 Don't Expose System Headers
57 ---------------------------
58
59 The System Library must shield LLVM from **all** system headers. To obtain
60 system level functionality, LLVM source must ``#include "llvm/System/Thing.h"``
61 and nothing else. This means that ``Thing.h`` cannot expose any system header
62 files. This protects LLVM from accidentally using system specific functionality
63 and only allows it via the ``lib/System`` interface.
64
65 Use Standard C Headers
66 ----------------------
67
68 The **standard** C headers (the ones beginning with "c") are allowed to be
69 exposed through the ``lib/System`` interface. These headers and the things they
70 declare are considered to be platform agnostic. LLVM source files may include
71 them directly or obtain their inclusion through ``lib/System`` interfaces.
72
73 Use Standard C++ Headers
74 ------------------------
75
76 The **standard** C++ headers from the standard C++ library and standard
77 template library may be exposed through the ``lib/System`` interface. These
78 headers and the things they declare are considered to be platform agnostic.
79 LLVM source files may include them or obtain their inclusion through
80 ``lib/System`` interfaces.
81
82 High Level Interface
83 --------------------
84
85 The entry points specified in the interface of ``lib/System`` must be aimed at
86 completing some reasonably high level task needed by LLVM. We do not want to
87 simply wrap each operating system call. It would be preferable to wrap several
88 operating system calls that are always used in conjunction with one another by
89 LLVM.
90
91 For example, consider what is needed to execute a program, wait for it to
92 complete, and return its result code. On Unix, this involves the following
93 operating system calls: ``getenv``, ``fork``, ``execve``, and ``wait``. The
94 correct thing for ``lib/System`` to provide is a function, say
95 ``ExecuteProgramAndWait``, that implements the functionality completely. what
96 we don't want is wrappers for the operating system calls involved.
97
98 There must **not** be a one-to-one relationship between operating system
99 calls and the System library's interface. Any such interface function will be
100 suspicious.
101
102 No Unused Functionality
103 -----------------------
104
105 There must be no functionality specified in the interface of ``lib/System``
106 that isn't actually used by LLVM. We're not writing a general purpose operating
107 system wrapper here, just enough to satisfy LLVM's needs. And, LLVM doesn't
108 need much. This design goal aims to keep the ``lib/System`` interface small and
109 understandable which should foster its actual use and adoption.
110
111 No Duplicate Implementations
112 ----------------------------
113
114 The implementation of a function for a given platform must be written exactly
115 once. This implies that it must be possible to apply a function's
116 implementation to multiple operating systems if those operating systems can
117 share the same implementation. This rule applies to the set of operating
118 systems supported for a given class of operating system (e.g. Unix, Win32).
119
120 No Virtual Methods
121 ------------------
122
123 The System Library interfaces can be called quite frequently by LLVM. In order
124 to make those calls as efficient as possible, we discourage the use of virtual
125 methods. There is no need to use inheritance for implementation differences, it
126 just adds complexity. The ``#include`` mechanism works just fine.
127
128 No Exposed Functions
129 --------------------
130
131 Any functions defined by system libraries (i.e. not defined by ``lib/System``)
132 must not be exposed through the ``lib/System`` interface, even if the header
133 file for that function is not exposed. This prevents inadvertent use of system
134 specific functionality.
135
136 For example, the ``stat`` system call is notorious for having variations in the
137 data it provides. ``lib/System`` must not declare ``stat`` nor allow it to be
138 declared. Instead it should provide its own interface to discovering
139 information about files and directories. Those interfaces may be implemented in
140 terms of ``stat`` but that is strictly an implementation detail. The interface
141 provided by the System Library must be implemented on all platforms (even those
142 without ``stat``).
143
144 No Exposed Data
145 ---------------
146
147 Any data defined by system libraries (i.e. not defined by ``lib/System``) must
148 not be exposed through the ``lib/System`` interface, even if the header file
149 for that function is not exposed. As with functions, this prevents inadvertent
150 use of data that might not exist on all platforms.
151
152 Minimize Soft Errors
153 --------------------
154
155 Operating system interfaces will generally provide error results for every
156 little thing that could go wrong. In almost all cases, you can divide these
157 error results into two groups: normal/good/soft and abnormal/bad/hard. That is,
158 some of the errors are simply information like "file not found", "insufficient
159 privileges", etc. while other errors are much harder like "out of space", "bad
160 disk sector", or "system call interrupted". We'll call the first group "*soft*"
161 errors and the second group "*hard*" errors.
162
163 ``lib/System`` must always attempt to minimize soft errors. This is a design
164 requirement because the minimization of soft errors can affect the granularity
165 and the nature of the interface. In general, if you find that you're wanting to
166 throw soft errors, you must review the granularity of the interface because it
167 is likely you're trying to implement something that is too low level. The rule
168 of thumb is to provide interface functions that **can't** fail, except when
169 faced with hard errors.
170
171 For a trivial example, suppose we wanted to add an "``OpenFileForWriting``"
172 function. For many operating systems, if the file doesn't exist, attempting to
173 open the file will produce an error. However, ``lib/System`` should not simply
174 throw that error if it occurs because its a soft error. The problem is that the
175 interface function, ``OpenFileForWriting`` is too low level. It should be
176 ``OpenOrCreateFileForWriting``. In the case of the soft "doesn't exist" error,
177 this function would just create it and then open it for writing.
178
179 This design principle needs to be maintained in ``lib/System`` because it
180 avoids the propagation of soft error handling throughout the rest of LLVM.
181 Hard errors will generally just cause a termination for an LLVM tool so don't
182 be bashful about throwing them.
183
184 Rules of thumb:
185
186 #. Don't throw soft errors, only hard errors.
187
188 #. If you're tempted to throw a soft error, re-think the interface.
189
190 #. Handle internally the most common normal/good/soft error conditions
191 so the rest of LLVM doesn't have to.
192
193 No throw Specifications
194 -----------------------
195
196 None of the ``lib/System`` interface functions may be declared with C++
197 ``throw()`` specifications on them. This requirement makes sure that the
198 compiler does not insert additional exception handling code into the interface
199 functions. This is a performance consideration: ``lib/System`` functions are at
200 the bottom of many call chains and as such can be frequently called. We need
201 them to be as efficient as possible. However, no routines in the system
202 library should actually throw exceptions.
203
204 Code Organization
205 -----------------
206
207 Implementations of the System Library interface are separated by their general
208 class of operating system. Currently only Unix and Win32 classes are defined
209 but more could be added for other operating system classifications. To
210 distinguish which implementation to compile, the code in ``lib/System`` uses
211 the ``LLVM_ON_UNIX`` and ``_WIN32`` ``#defines``. Each source file in
212 ``lib/System``, after implementing the generic (operating system independent)
213 functionality needs to include the correct implementation using a set of
214 ``#if defined(LLVM_ON_XYZ)`` directives. For example, if we had
215 ``lib/System/File.cpp``, we'd expect to see in that file:
216
217 .. code-block:: c++
218
219 #if defined(LLVM_ON_UNIX)
220 #include "Unix/File.cpp"
221 #endif
222 #if defined(_WIN32)
223 #include "Win32/File.cpp"
224 #endif
225
226 The implementation in ``lib/System/Unix/File.cpp`` should handle all Unix
227 variants. The implementation in ``lib/System/Win32/File.cpp`` should handle all
228 Win32 variants. What this does is quickly differentiate the basic class of
229 operating system that will provide the implementation. The specific details for
230 a given platform must still be determined through the use of ``#ifdef``.
231
232 Consistent Semantics
233 --------------------
234
235 The implementation of a ``lib/System`` interface can vary drastically between
236 platforms. That's okay as long as the end result of the interface function is
237 the same. For example, a function to create a directory is pretty straight
238 forward on all operating system. System V IPC on the other hand isn't even
239 supported on all platforms. Instead of "supporting" System V IPC,
240 ``lib/System`` should provide an interface to the basic concept of
241 inter-process communications. The implementations might use System V IPC if
242 that was available or named pipes, or whatever gets the job done effectively
243 for a given operating system. In all cases, the interface and the
244 implementation must be semantically consistent.
245
7 The System Library has been renamed to Support Library with documentation
8 available at :doc:`SupportLibrary`. Please, change your links to that page.
271271 GoldPlugin
272272 MarkedUpDisassembly
273273 SystemLibrary
274 SupportLibrary
274275 SourceLevelDebugging
275276 Vectorizers
276277 WritingAnLLVMBackend
345346 :doc:`BitCodeFormat`
346347 This describes the file format and encoding used for LLVM "bc" files.
347348
348 :doc:`System Library `
349 This document describes the LLVM System Library (``lib/System``) and
349 :doc:`Support Library `
350 This document describes the LLVM Support Library (``lib/Support``) and
350351 how to keep LLVM source code portable
351352
352353 :doc:`LinkTimeOptimization`