Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / llvm / c24d48282b44008e44f80509d76dfa3d18ddf168 / . / docs / SystemLibrary.html
blob: 9858cdb40a1b81971928bd7768068029d7804ee9 [file] [log] [blame]
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
3<html>
4<head>
5 <title>System Library</title>
6 <link rel="stylesheet" href="llvm.css" type="text/css">
7</head>
8<body>
9
Misha Brukmanebbbf252004-07-21 18:02:43 +0000[diff] [blame]10<div class="doc_title">System Library</div>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]11
Misha Brukmanebbbf252004-07-21 18:02:43 +0000[diff] [blame]12<div class="doc_warning">
13 <p>Warning: This document is a work in progress.</p>
14</div>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]15
16<ul>
17 <li><a href="#abstract">Abstract</a></li>
18 <li><a href="#requirements">System Library Requirements</a>
19 <ol>
20 <li><a href="#headers">Hide System Header Files</a></li>
Reid Spencer7acb8662004-08-27 02:08:04 +0000[diff] [blame]21 <li><a href="#c_headers">Allow Standard C Header Files</a></li>
22 <li><a href="#cpp_headers">Allow Standard C++ Header Files</a></li>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]23 <li><a href="#nofunc">No Exposed Functions</a></li>
24 <li><a href="#nodata">No Exposed Data</a></li>
Reid Spencer7acb8662004-08-27 02:08:04 +0000[diff] [blame]25 <li><a href="#throw">Throw Only std::string</a></li>
26 <li><a href="#throw_spec">No throw() Specifications</a></li>
27 <li><a href="#nodupl">No Duplicate Impementations</a></li>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]28 </ol></li>
29 <li><a href="#design">System Library Design</a>
30 <ol>
Reid Spencer7acb8662004-08-27 02:08:04 +0000[diff] [blame]31 <li><a href="#nounused">No Unused Functionality</a></li>
32 <li><a href="#highlev">High-Level Interface</a></li>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]33 <li><a href="#opaque">Use Opaque Classes</a></li>
34 <li><a href="#common">Common Implementations</a></li>
35 <li><a href="#multi_imps">Multiple Implementations</a></li>
36 <li><a href="#lowlevel">Use Low Level Interfaces</a></li>
37 <li><a href="#memalloc">No Memory Allocation</a></li>
38 <li><a href="#virtuals">No Virtual Methods</a></li>
39 </ol></li>
40 <li><a href="#detail">System Library Details</a>
41 <ol>
42 <li><a href="#bug">Tracking Bugzilla Bug: 351</a></li>
43 <li><a href="#refimpl">Reference Implementatation</a></li>
44 </ol></li>
45</ul>
46
47<div class="doc_author">
Misha Brukman17217842004-07-21 18:04:27 +0000[diff] [blame]48 <p>Written by <a href="rspencer@x10sys.com">Reid Spencer</a></p>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]49</div>
50
51
52<!-- *********************************************************************** -->
53<div class="doc_section"><a name="abstract">Abstract</a></div>
54<div class="doc_text">
55 <p>This document describes the requirements, design, and implementation
56 details of LLVM's System Library. The library is composed of the header files
57 in <tt>llvm/include/llvm/System</tt> and the source files in
58 <tt>llvm/lib/System</tt>. The goal of this library is to completely shield
59 LLVM from the variations in operating system interfaces. By centralizing
60 LLVM's use of operating system interfaces, we make it possible for the LLVM
Reid Spencer7acb8662004-08-27 02:08:04 +0000[diff] [blame]61 tool chain and runtime libraries to be more easily ported to new platforms
62 since (theoretically) only <tt>llvm/lib/System</tt> needs to be ported. This
63 library also unclutters the rest of LLVM from #ifdef use and special
64 cases for specific operating systems. Such uses are replaced with simple calls
65 to the interfaces provided in <tt>llvm/include/llvm/System</tt>.</p> Note that
66 lib/System is not intended to be a complete operating system wrapper (such as
67 the Adaptive Communications Environment (ACE) or Apache Portable Runtime
68 (APR)), but only to provide the functionality necessary to support LLVM.
69 <p>The System Library was written by Reid Spencer who formulated the
70 design based on similar original work as part of the eXtensible Programming
71 System (XPS).</p>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]72</div>
73
74<!-- *********************************************************************** -->
75<div class="doc_section">
76 <a name="requirements">System Library Requirements</a>
77</div>
78<div class="doc_text">
79 <p>The System library's requirements are aimed at shielding LLVM from the
80 variations in operating system interfaces. The following sections define the
Reid Spencer7acb8662004-08-27 02:08:04 +0000[diff] [blame]81 requirements needed to fulfill this objective. Of necessity, these requirements
82 must be strictly followed in order to ensure the library's goal is reached.</p>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]83</div>
84
85<!-- ======================================================================= -->
86<div class="doc_subsection"><a name="headers">Hide System Header Files</a></div>
87<div class="doc_text">
Reid Spencer7acb8662004-08-27 02:08:04 +0000[diff] [blame]88 <p>The library must sheild LLVM from <em>all</em> system libraries. To obtain
89 system level functionality, LLVM must <tt>#include "llvm/System/Thing.h"</tt>
90 and nothing else. This means that <tt>Thing.h</tt> cannot expose any system
91 header files. This protects LLVM from accidentally using system specific
92 functionality except through the lib/System interface. Specifically this
93 means that header files like "unistd.h", "windows.h", "stdio.h", and
94 "string.h" are verbotten outside the implementation of lib/System.
95 </p>
96</div>
97
98<!-- ======================================================================= -->
99<div class="doc_subsection"><a name="c_headers">Allow Standard C Headers</a>
100</div>
101<div class="doc_text">
102 <p>The <em>standard</em> C headers (the ones beginning with "c") are allowed
103 to be exposed through the lib/System interface. These headers and the things
104 they declare are considered to be platform agnostic. LLVM source files may
105 include them or obtain their inclusion through lib/System interfaces.</p>
106</div>
107
108<!-- ======================================================================= -->
109<div class="doc_subsection"><a name="cpp_headers">Allow Standard C++ Headers</a>
110</div>
111<div class="doc_text">
112 <p>The <em>standard</em> C++ headers from the standard C++ library and
113 standard template library are allowed to be exposed through the lib/System
114 interface. These headers and the things they declare are considered to be
115 platform agnostic. LLVM source files may include them or obtain their
116 inclusion through lib/System interfaces.</p>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]117</div>
118
119<!-- ======================================================================= -->
120<div class="doc_subsection"><a name="nofunc">No Exposed Functions</a></div>
121<div class="doc_text">
Reid Spencer7acb8662004-08-27 02:08:04 +0000[diff] [blame]122 <p>Any functions defined by system libraries (i.e. not defined by lib/System)
123 must not be exposed through the lib/System interface, even if the header file
124 for that function is not exposed. This prevents inadvertent use of system
125 specific functionality.</p>
126 <p>For example, the <tt>stat</tt> system call is notorious for having
127 variations in the data it provides. lib/System must not declare <tt>stat</tt>
128 nor allow it to be declared. Instead it should provide its own interface to
129 discovering information about files and directories. Those interfaces may be
130 implemented in terms of <tt>stat</tt> but that is strictly an implementation
131 detail.</p>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]132</div>
133
134<!-- ======================================================================= -->
135<div class="doc_subsection"><a name="nodata">No Exposed Data</a></div>
136<div class="doc_text">
Reid Spencer7acb8662004-08-27 02:08:04 +0000[diff] [blame]137 <p>Any data defined by system libraries (i.e. not defined by lib/System) must
138 not be exposed through the lib/System interface, even if the header file for
139 that function is not exposed. As with functions, this prevents inadvertent use
140 of data that might not exist on all platforms.</p>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]141</div>
142
143<!-- ======================================================================= -->
Reid Spencer7acb8662004-08-27 02:08:04 +0000[diff] [blame]144<div class="doc_subsection"><a name="throw">Throw Only std::string</a></div>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]145<div class="doc_text">
Reid Spencer7acb8662004-08-27 02:08:04 +0000[diff] [blame]146 <p>If an error occurs that lib/System cannot handle, the only action taken by
147 lib/System is to throw an instance of std:string. The contents of the string
148 must explain both what happened and the context in which it happened. The
149 format of the string should be a (possibly empty) list of contexts each
150 terminated with a : and a space, followed by the error message, optionally
151 followed by a reason, and optionally followed by a suggestion.</p>
152 <p>For example, failure to open a file named "foo" could result in a message
153 like:</p>
154 <ul><li>foo: Unable to open file because it doesn't exist."</li></ul>
155 <p>The "foo:" part is the context. The "Unable to open file" part is the error
156 message. The "because it doesn't exist." part is the reason. This message has
157 no suggestion. Where possible, the imlementation of lib/System should use
158 operating system specific facilities for converting the error code returned by
159 a system call into an error message. This will help to make the error message
160 more familiar to users of that type of operating system.</p>
161 <p>Note that this requirement precludes the throwing of any other exceptions.
162 For example, various C++ standard library functions can cause exceptions to be
163 thrown (e.g. out of memory situation). In all cases, if there is a possibility
164 that non-string exceptions could be thrown, the lib/System library must ensure
165 that the exceptions are translated to std::string form.</p>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]166</div>
167
168<!-- ======================================================================= -->
Reid Spencer7acb8662004-08-27 02:08:04 +0000[diff] [blame]169<div class="doc_subsection"><a name="throw_spec">No throw Specifications</a>
170</div>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]171<div class="doc_text">
Reid Spencer7acb8662004-08-27 02:08:04 +0000[diff] [blame]172 <p>None of the lib/System interface functions may be declared with C++
173 <tt>throw()</tt> specifications on them. This requirement makes sure that the
174 compler does not insert addtional exception handling code into the interface
175 functions. This is a performance consideration: lib/System functions are at
176 the bottom of the many call chains and as such can be frequently called. We
177 need them to be as efficient as possible.</p>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]178</div>
179
180<!-- ======================================================================= -->
Reid Spencer7acb8662004-08-27 02:08:04 +0000[diff] [blame]181<div class="doc_subsection"><a name="nodupl">No Duplicate Implementations</a>
182</div>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]183<div class="doc_text">
Reid Spencer7acb8662004-08-27 02:08:04 +0000[diff] [blame]184 <p>The implementation of a function for a given platform must be written
185 exactly once. This implies that it must be possible to apply a function's
186 implementation to multiple operating systems if those operating systems can
187 share the same implementation.</p>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]188</div>
189
190<!-- *********************************************************************** -->
191<div class="doc_section"><a name="design">System Library Design</a></div>
192<div class="doc_text">
193 <p>In order to fulfill the requirements of the system library, strict design
194 objectives must be maintained in the library as it evolves. The goal here
195 is to provide interfaces to operating system concepts (files, memory maps,
196 sockets, signals, locking, etc) efficiently and in such a way that the
197 remainder of LLVM is completely operating system agnostic.</p>
198</div>
199
200<!-- ======================================================================= -->
Reid Spencer7acb8662004-08-27 02:08:04 +0000[diff] [blame]201<div class="doc_subsection"><a name="nounused">No Unused Functionality</a></div>
202<div class="doc_text">
203 <p>There must be no functionality specified in the interface of lib/System
204 that isn't actually used by LLVM. We're not writing a general purpose
205 operating system wrapper here, just enough to satisfy LLVM's needs. And, LLVM
206 doesn't need much. This design goal aims to keep the lib/System interface
207 small and understandable which should foster its actual use and adoption.</p>
208</div>
209
210<!-- ======================================================================= -->
211<div class="doc_subsection"><a name="highlev">High Level Interface</a></div>
212<div class="doc_text">
213 <p>The entry points specified in the interface of lib/System must be aimed at
214 completing some reasonably high level task needed by LLVM. We do not want to
215 simply wrap each operating system call. It would be preferable to wrap several
216 operating system calls that are always used in conjunction with one another by
217 LLVM.</p>
218 <p>For example, consider what is needed to execute a program, wait for it to
219 complete, and return its result code. On Unix, this involves the following
220 operating system calls: <tt>getenv, fork, execve,</tt> and <tt>wait</tt>. The
221 correct thing for lib/System to provide is a function, say
222 <tt>ExecuteProgramAndWait</tt>, that implements the functionality completely.
223 what we don't want is wrappers for the operating system calls involved.</p>
224 <p>There must <em>not</em> be a one-to-one relationship between operating
225 system calls and the System library's interface. Any such interface function
226 will be suspicious.</p>
227</div>
228
229<!-- ======================================================================= -->
230<div class="doc_subsection"><a name="highlev">Minimize Soft Errors</a></div>
231<div class="doc_text">
232 <p>Operating system interfaces will generally provide errors results for every
233 little thing that could go wrong. In almost all cases, you can divide these
234 error results into two groups: normal/good/soft and abnormal/bad/hard. That
235 is, some of the errors are simply information like "file not found",
236 "insufficient privileges", etc. while other errors are much harder like
237 "out of space", "bad disk sector", or "system call interrupted". Well call the
238 first group "soft" errors and the second group "hard" errors.<p>
239 <p>lib/System must always attempt to minimize soft errors and always just
240 throw a std::string on hard errors. This is a design requirement because the
241 minimization of soft errors can affect the granularity and the nature of the
242 interface. In general, if you find that you're wanting to throw soft errors,
243 you must review the granularity of the interface because it is likely you're
244 trying to implement something that is too low level. The rule of thumb is to
245 provide interface functions that "can't" fail, except when faced with hard
246 errors.</p>
247 <p>For a trivial example, suppose we wanted to add an "OpenFileForWriting"
248 function. For many operating systems, if the file doesn't exist, attempting
249 to open the file will produce an error. However, lib/System should not
250 simply throw that error if it occurs because its a soft error. The problem
251 is that the interface function, OpenFileForWriting is too low level. It should
252 be OpenOrCreateFileForWriting. In the case of the soft "doesn't exist" error,
253 this function would just create it and then open it for writing.</p>
254 <p>This design principle needs to be maintained in lib/System because it
255 avoids the propagation of soft error handling throughout the rest of LLVM.
256 Hard errors will generally just cause a termination for an LLVM tool so don't
257 be bashful about throwing them.</p>
258 <p>Rules of thumb:</p>
259 <ol>
260 <li>Don't throw soft errors, only hard errors.</li>
261 <li>If you're tempted to throw a soft error, re-think the interface.</li>
262 <li>Handle internally the most common normal/good/soft error conditions
263 so the rest of LLVM doesn't have to.</li>
264 </ol>
265
266<pre><tt>
267Notes:
26810. The implementation of a lib/System interface can vary drastically between
269 platforms. That's okay as long as the end result of the interface function is
270 the same. For example, a function to create a directory is pretty straight
271 forward on all operating system. System V IPC on the other hand isn't even
272 supported on all platforms. Instead of "supporting" System V IPC, lib/System
273 should provide an interface to the basic concept of inter-process
274 communications. The implementations might use System V IPC if that was
275 available or named pipes, or whatever gets the job done effectively for a
276 given operating system.
277
27811. Implementations are separated first by the general class of operating system
279 as provided by the configure script's $build variable. This variable is used
280 to create a link from $BUILD_OBJ_ROOT/lib/System/platform to a directory in
281 $BUILD_SRC_ROOT/lib/System directory with the same name as the $build
282 variable. This provides a retargetable include mechanism. By using the link's
283 name (platform) we can actually include the operating specific
284 implementation. For example, support $build is "Darwin" for MacOS X. If we
285 place:
286 #include "platform/File.cpp"
287 into a a file in lib/System, it will actually include
288 lib/System/Darwin/File.cpp. What this does is quickly differentiate the basic
289 class of operating system that will provide the implementation.
290
29112. Implementation files in lib/System need may only do two things: (1) define
292 functions and data that is *TRULY* generic (completely platform agnostic) and
293 (2) #include the platform specific implementation with:
294
295 #include "platform/Impl.cpp"
296
297 where Impl is the name of the implementation files.
298
29913. Platform specific implementation files (platform/Impl.cpp) may only #include
300 other Impl.cpp files found in directories under lib/System. The order of
301 inclusion is very important (from most generic to most specific) so that we
302 don't inadvertently place an implementation in the wrong place. For example,
303 consider a fictitious implementation file named DoIt.cpp. Here's how the
304 #includes should work for a Linux platform
305
306 lib/System/DoIt.cpp
307 #include "platform/DoIt.cpp" // platform specific impl. of Doit
308 DoIt
309
310 lib/System/Linux/DoIt.cpp // impl that works on all Linux
311 #include "../Unix/DoIt.cpp" // generic Unix impl. of DoIt
312 #include "../Unix/SUS/DoIt.cpp // SUS specific impl. of DoIt
313 #include "../Unix/SUS/v3/DoIt.cpp // SUSv3 specific impl. of DoIt
314
315 Note that the #includes in lib/System/Linux/DoIt.cpp are all optional but
316 should be used where the implementation of some functionality can be shared
317 across some set of Unix variants. We don't want to duplicate code across
318 variants if their implementation could be shared.
319</tt></pre>
320</div>
321
322<!-- ======================================================================= -->
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]323<div class="doc_subsection"><a name="opaque">Use Opaque Classes</a></div>
324<div class="doc_text">
325 <p>no public data</p>
326 <p>onlyprimitive typed private/protected data</p>
327 <p>data size is "right" for platform, not max of all platforms</p>
328 <p>each class corresponds to O/S concept</p>
329</div>
330
331<!-- ======================================================================= -->
332<div class="doc_subsection"><a name="common">Common Implementations</a></div>
333<div class="doc_text">
334 <p>To be written.</p>
335</div>
336
337<!-- ======================================================================= -->
338<div class="doc_subsection">
339 <a name="multi_imps">Multiple Implementations</a>
340</div>
341<div class="doc_text">
342 <p>To be written.</p>
343</div>
344
345<!-- ======================================================================= -->
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]346<div class="doc_subsection"><a name="memalloc">No Memory Allocation</a></div>
347<div class="doc_text">
348 <p>To be written.</p>
349</div>
350
351<!-- ======================================================================= -->
352<div class="doc_subsection"><a name="virtuals">No Virtual Methods</a></div>
353<div class="doc_text">
354 <p>To be written.</p>
355</div>
356
357<!-- *********************************************************************** -->
358<div class="doc_section"><a name="detail">System Library Details</a></div>
359<div class="doc_text">
360 <p>To be written.</p>
361</div>
362
363<!-- ======================================================================= -->
Chris Lattner05540a72004-07-17 18:50:19 +0000[diff] [blame]364<div class="doc_subsection"><a name="bug">Bug 351</a></div>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]365<div class="doc_text">
Chris Lattner05540a72004-07-17 18:50:19 +0000[diff] [blame]366 <p>See <a href="http://llvm.cs.uiuc.edu/PR351">bug 351</a>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]367 for further details on the progress of this work</p>
368</div>
369
370<!-- ======================================================================= -->
Reid Spencer95189202004-08-26 18:52:52 +0000[diff] [blame]371<div class="doc_subsection"><a name="bug">Rationale For #include Hierarchy</a>
372</div>
373<div class="doc_text">
374 <p>In order to provide different implementations of the lib/System interface
375 for different platforms, it is necessary for the library to "sense" which
376 operating system is being compiled for and conditionally compile only the
377 applicabe parts of the library. While several operating system wrapper
378 libraries (e.g. APR, ACE) choose to use #ifdef preprocessor statements in
379 combination with autoconf variable (HAVE_* family), lib/System chooses an
380 alternate strategy. <p>
381 <p>To put it succinctly, the lib/System strategy has traded "#ifdef hell" for
382 "#include hell". That is, a given implementation file defines one or more
383 functions for a particular operating system variant. The functions defined in
384 that file have no #ifdef's to disambiguate the platform since the file is only
385 compiled on one kind of platform. While this leads to the same function being
386 imlemented differently in different files, it is our contention that this
387 leads to better maintenance and easier portability.</p>
388 <p>For example, consider a function having different implementations on a
389 variety of platforms. Many wrapper libraries choose to deal with the different
390 implementations by using #ifdef, like this:</p>
391 <pre><tt>
392 void SomeFunction(void) {
393 #if defined __LINUX
394 // .. Linux implementation
395 #elif defined __WIN32
396 // .. Win32 implementation
397 #elif defined __SunOS
398 // .. SunOS implementation
399 #else
400 #warning "Don't know how to implement SomeFunction on this platform"
401 #endif
402 }
403 </tt></pre>
404 <p>The problem with this is that its very messy to read, especially as the
405 number of operating systems and their variants grow. The above example is
406 actually tame compared to what can happen when the implementation depends on
407 specific flavors and versions of the operating system. In that case you end up
408 with multiple levels of nested #if statements. This is what we mean by "#ifdef
409 hell".</p>
410 <p>To avoid the situation above, we've choosen to locate all functions for a
411 given implementation file for a specific operating system into one place. This
412 has the following advantages:<p>
413 <ul>
414 <li>No "#ifdef hell"</li>
415 <li>When porting, the strategy is quite straight forward: copy the
416 implementation file from a similar operating system to a new directory and
417 re-implement them.<li>
418 <li>Correctness is helped during porting because the new operating system's
419 implementation is wholly contained in a separate directory. There's no
420 chance to make an error in the #if statements and affect some other
421 operating system's implementation.</li>
422 </ul>
423 <p>So, given that we have decided to use #include instead of #if to provide
424 platform specific implementations, there are actually three ways we can go
425 about doing this. None of them are perfect, but we believe we've chosen the
426 lesser of the three evils. Given that there is a variable named $OS which
427 names the platform for which we must build, here's a summary of the three
428 approaches we could use to determine the correct directory:</p>
429 <ol>
430 <li>Provide the compiler with a -I$(OS) on the command line. This could be
431 provided in only the lib/System makefile.</li>
432 <li>Use autoconf to transform #include statements in the implementation
433 files by using substitutions of @OS@. For example, if we had a file,
434 File.cpp.in, that contained "#include &lt;@OS@/File.cpp&gt;" this would get
435 transformed to "#include &lt;actual/File.cpp&gt;" where "actual" is the
436 actual name of the operating system</li>
437 <li>Create a link from $OBJ_DIR/platform to $SRC_DIR/$OS. This allows us to
438 use a generic directory name to get the correct platform, as in #include
439 &lt;platform/File.cpp&gt;</li>
440 </ol>
441 <p>Let's look at the pitfalls of each approach.</p>
442 <p>In approach #1, we end up with some confusion as to what gets included.
443 Suppose we have lib/System/File.cpp that includes just File.cpp to get the
444 platform specific part of the implementation. In this case, the include
445 directive with the &lt;&gt; syntax will include the right file but the include
446 directive with the "" syntax will recursively include the same file,
447 lib/System/File.cpp. In the case of #include &lt;File.cpp&gt;, the -I options
448 to the compiler are searched first so it works. But in the #include "File.cpp"
449 case, the current directory is searched first. Furthermore, in both cases,
450 neither include directive documents which File.cpp is getting included.</p>
451 <p>In approach #2, we have the problem of needing to reconfigure repeatedly.
452 Developer's generally hate that and we don't want lib/System to be a thorn in
453 everyone's side because it will constantly need updating as operating systems
454 change and as new operating systems are added. The problem occurs when a new
455 implementation file is added to the library. First of all, you have to add a
456 file with the .in suffix, then you have to add that file name to the list of
457 configurable files in the autoconf/configure.ac file, then you have to run
458 AutoRegen.sh to rebuild the configure script, then you have to run the
459 configure script. This is deemed to be a pretty large hassle.</p>
460 <p>In approach #3, we have the problem that not all platforms support links.
461 Fortunately the autoconf macro used to create the link can compensate for
462 this. If a link can't be made, the configure script will copy the correct
463 directory from $BUILD_SRC_DIR to $BUILD_OBJ_DIR under the new name. The only
464 problem with this is that if a copy is made, the copy doesn't get updated if
465 the programmer adds or modifies files in the $BUILD_SRC_DIR. A reconfigure or
466 manual copying is needed to get things to compile.<p>
467 <p>The approach we have taken in lib/System is #3. Here's why:<p>
468 <ul>
469 <li>Approach #1 is rejected because it doesn't document what's actually
470 getting included and the potential for mistakes with alternate include
471 directive forms is high.</li>
472 <li>Approach #2 are both viable and only really impact development when new
473 files are added to the library.</li>
474 <li>However, approach #2 impacts every new file on every platform all the
475 time. With approach #3, only those platforms not supporting links will be
476 affected. The number of platforms not supporting links is very small and
477 they are generally archaic.</li>
478 <li>Given the above, approach #3 seems to have the least impact.</li>
479 </ul>
480</div>
481
482<!-- ======================================================================= -->
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]483<div class="doc_subsection">
484 <a name="refimpl">Reference Implementation</a>
485</div>
486<div class="doc_text">
487 <p>The <tt>linux</tt> implementation of the system library will always be the
488 reference implementation. This means that (a) the concepts defined by the
489 linux must be identically replicated in the other implementations and (b) the
490 linux implementation must always be complete (provide implementations for all
491 concepts).</p>
492</div>
493
494<!-- *********************************************************************** -->
495
496<hr>
497<address>
498 <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
499 src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
500 <a href="http://validator.w3.org/check/referer"><img
501 src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
502
503 <a href="mailto:rspencer@x10sys.com">Reid Spencer</a><br>
504 <a href="http://llvm.cs.uiuc.edu">LLVM Compiler Infrastructure</a><br>
505 Last modified: $Date$
506</address>
507</body>
508</html>