From 30d479c28c831a0d4f1fdb54a9e346b0fc176be1 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Wed, 17 Apr 2024 08:23:09 +0200 Subject: Adding upstream version 1.7.2. Signed-off-by: Daniel Baumann --- docs/APRDesign.html | 399 ++++++++++++++++++++++++++++++++++++++++++ docs/canonical_filenames.html | 156 +++++++++++++++++ docs/doxygen.conf | 38 ++++ docs/incomplete_types | 84 +++++++++ docs/non_apr_programs | 47 +++++ docs/pool-design.html | 96 ++++++++++ docs/win32_builds.html | 57 ++++++ 7 files changed, 877 insertions(+) create mode 100644 docs/APRDesign.html create mode 100644 docs/canonical_filenames.html create mode 100644 docs/doxygen.conf create mode 100644 docs/incomplete_types create mode 100644 docs/non_apr_programs create mode 100644 docs/pool-design.html create mode 100644 docs/win32_builds.html (limited to 'docs') diff --git a/docs/APRDesign.html b/docs/APRDesign.html new file mode 100644 index 0000000..0d6d6a5 --- /dev/null +++ b/docs/APRDesign.html @@ -0,0 +1,399 @@ + +APR Design Document + +

Design of APR

+ +

The Apache Portable Run-time libraries have been designed to provide a common +interface to low level routines across any platform. The original goal of APR +was to combine all code in Apache to one common code base. This is not the +correct approach however, so the goal of APR has changed. There are places +where common code is not a good thing. For example, how to map requests +to either threads or processes should be platform specific. APR's place +is now to combine any code that can be safely combined without sacrificing +performance.

+ +

To this end we have created a set of operations that are required for cross +platform development. There may be other types that are desired and those +will be implemented in the future.

+ +

This document will discuss the structure of APR, and how best to contribute +code to the effort.

+ +

APR On Windows and Netware

+ +

APR on Windows and Netware is different from APR on all other systems, +because those platforms don't use autoconf. On Unix, apr_private.h (private to +APR) and apr.h (public, used by applications that use APR) are generated by +autoconf from acconfig.h and apr.h.in respectively. On Windows (and Netware), +apr_private.h and apr.h are created from apr_private.hw (apr_private.hwn) +and apr.hw (apr.hwn) respectively.

+ +

+ If you add code to acconfig.h or tests to configure.in or aclocal.m4, + please give some thought to whether or not Windows and Netware need + these additions as well. A general rule of thumb, is that if it is + a feature macro, such as APR_HAS_THREADS, Windows and Netware need it. + In other words, if the definition is going to be used in a public APR + header file, such as apr_general.h, Windows needs it. + + The only time it is safe to add a macro or test without also adding + the macro to apr*.h[n]w, is if the macro tells APR how to build. For + example, a test for a header file does not need to be added to Windows. +

+ +

APR Features

+ +

One of the goals of APR is to provide a common set of features across all +platforms. This is an admirable goal, it is also not realistic. We cannot +expect to be able to implement ALL features on ALL platforms. So we are +going to do the next best thing. Provide a common interface to ALL APR +features on MOST platforms.

+ +

APR developers should create FEATURE MACROS for any feature that is not +available on ALL platforms. This should be a simple definition which has +the form:

+ +APR_HAS_FEATURE + +

This macro should evaluate to true if APR has this feature on this platform. +For example, Linux and Windows have mmap'ed files, and APR is providing an +interface for mmapp'ing a file. On both Linux and Windows, APR_HAS_MMAP +should evaluate to one, and the ap_mmap_* functions should map files into +memory and return the appropriate status codes.

+ +

If your OS of choice does not have mmap'ed files, APR_HAS_MMAP should +evaluate to zero, and all ap_mmap_* functions should not be defined. The +second step is a precaution that will allow us to break at compile time if a +programmer tries to use unsupported functions.

+ +

APR types

+ +

The base types in APR

+ + + +

Directory Structure

+ +

Each type has a base directory. Inside this base directory, are +subdirectories, which contain the actual code. These subdirectories are named +after the platforms the are compiled on. Unix is also used as a common +directory. If the code you are writing is POSIX based, you should look at the +code in the unix directory. A good rule of thumb, is that if more than half +your code needs to be ifdef'ed out, and the structures required for your code +are substantively different from the POSIX code, you should create a new +directory.

+ +

Currently, the APR code is written for Unix, BeOS, Windows, and OS/2. An +example of the directory structure is the file I/O directory:

+ +
+apr
+  |
+   ->  file_io
+          |
+           -> unix            The Unix and common base code
+          |
+           -> win32           The Windows code
+          | 
+           -> os2             The OS/2 code
+
+ +

Obviously, BeOS does not have a directory. This is because BeOS is currently +using the Unix directory for it's file_io.

+ +

There are a few special top level directories. These are test and include. +Test is a directory which stores all test programs. It is expected +that if a new type is developed, there will also be a new test program, to +help people port this new type to different platforms. A small document +describing how to create new tests that integrate with the test suite can be +found in the test/ directory. Include is a directory which stores all +required APR header files for external use.

+ +

Creating an APR Type

+ +

The current design of APR requires that most APR types be incomplete. +It is not possible to write flexible portable code if programs can access +the internals of APR types. This is because different platforms are +likely to define different native types. There are only two exceptions to +this rule:

+ + + +

For this reason, each platform defines a structure in their own directories. +Those structures are then typedef'ed in an external header file. For example +in file_io/unix/fileio.h:

+ +
+    struct ap_file_t {
+        apr_pool_t *cntxt;
+        int filedes;
+        FILE *filehand;
+        ...
+    }
+
+ +

In include/apr_file_io.h:

+ + typedef struct ap_file_t ap_file_t; + + +

This will cause a compiler error if somebody tries to access the filedes +field in this structure. Windows does not have a filedes field, so obviously, +it is important that programs not be able to access these.

+ +

You may notice the apr_pool_t field. Most APR types have this field. This +type is used to allocate memory within APR. Because every APR type has a pool, +any APR function can allocate memory if it needs to. This is very important +and it is one of the reasons that APR works. If you create a new type, you +must add a pool to it. If you do not, then all functions that operate on that +type will need a pool argument.

+ +

New Function

+ +

When creating a new function, please try to adhere to these rules.

+ + + +

Documentation

+ +

Whenever a new function is added to APR, it MUST be documented. New +functions will not be committed unless there are docs to go along with them. +The documentation should be a comment block above the function in the header +file.

+ +

The format for the comment block is:

+ +
+    /**
+     * Brief description of the function
+     * @param parma_1_name explanation
+     * @param parma_2_name explanation
+     * @param parma_n_name explanation
+     * @tip Any extra information people should know.
+     * @deffunc function prototype if required
+     */ 
+
+ +

For an actual example, look at any file in the include directory. The +reason the docs are in the header files is to ensure that the docs always +reflect the current code. If you change parameters or return values for a +function, please be sure to update the documentation.

+ +

APR Error reporting

+ +

Most APR functions should return an ap_status_t type. The only time an +APR function does not return an ap_status_t is if it absolutely CAN NOT +fail. Examples of this would be filling out an array when you know you are +not beyond the array's range. If it cannot fail on your platform, but it +could conceivably fail on another platform, it should return an ap_status_t. +Unless you are sure, return an ap_status_t.

+ + + This includes functions that return TRUE/FALSE values. How that + is handled is discussed below + + +

All platforms return errno values unchanged. Each platform can also have +one system error type, which can be returned after an offset is added. +There are five types of error values in APR, each with its own offset.

+ + +
+    Name			Purpose
+0) 			This is 0 for all platforms and isn't really defined
+ 			anywhere, but it is the offset for errno values.
+			(This has no name because it isn't actually defined, 
+                        but for completeness we are discussing it here).
+
+1) APR_OS_START_ERROR	This is platform dependent, and is the offset at which
+			APR errors start to be defined.  Error values are 
+			defined as anything which caused the APR function to 
+			fail.  APR errors in this range should be named 
+			APR_E* (i.e. APR_ENOSOCKET)
+
+2) APR_OS_START_STATUS	This is platform dependent, and is the offset at which
+			APR status values start.  Status values do not indicate
+			success or failure, and should be returned if 
+			APR_SUCCESS does not make sense.  APR status codes in 
+			this range should be name APR_* (i.e. APR_DETACH)
+
+4) APR_OS_START_USEERR	This is platform dependent, and is the offset at which
+			APR apps can begin to add their own error codes.
+
+3) APR_OS_START_SYSERR	This is platform dependent, and is the offset at which
+			system error values begin.
+
+ +The difference in naming between APR_OS_START_ERROR and +APR_OS_START_STATUS mentioned above allows programmers to easily determine if +the error code indicates an error condition or a status condition. + +

If your function has multiple return codes that all indicate success, but +with different results, or if your function can only return PASS/FAIL, you +should still return an apr_status_t. In the first case, define one +APR status code for each return value, an example of this is +apr_proc_wait, which can only return APR_CHILDDONE, +APR_CHILDNOTDONE, or an error code. In the second case, please return +APR_SUCCESS for PASS, and define a new APR status code for failure, an +example of this is apr_compare_users, which can only return +APR_SUCCESS, APR_EMISMATCH, or an error code.

+ +

All of these definitions can be found in apr_errno.h for all platforms. When +an error occurs in an APR function, the function must return an error code. +If the error occurred in a system call and that system call uses errno to +report an error, then the code is returned unchanged. For example:

+ +
+    if (open(fname, oflags, 0777) < 0)
+        return errno;
+
+ +

The next place an error can occur is a system call that uses some error value +other than the primary error value on a platform. This can also be handled +by APR applications. For example:

+ +
+    if (CreateFile(fname, oflags, sharemod, NULL, 
+                   createflags, attributes, 0) == INVALID_HANDLE_VALUE
+        return (GetLAstError() + APR_OS_START_SYSERR);
+
+ +

These two examples implement the same function for two different platforms. +Obviously even if the underlying problem is the same on both platforms, this +will result in two different error codes being returned. This is OKAY, and +is correct for APR. APR relies on the fact that most of the time an error +occurs, the program logs the error and continues, it does not try to +programatically solve the problem. This does not mean we have not provided +support for programmatically solving the problem, it just isn't the default +case. We'll get to how this problem is solved in a little while.

+ +

If the error occurs in an APR function but it is not due to a system call, +but it is actually an APR error or just a status code from APR, then the +appropriate code should be returned. These codes are defined in apr_errno.h +and should be self explanatory.

+ +

No APR code should ever return a code between APR_OS_START_USEERR and +APR_OS_START_SYSERR, those codes are reserved for APR applications.

+ +

To programmatically correct an error in a running application, the error +codes need to be consistent across platforms. This should make sense. APR +has provided macros to test for status code equivalency. For example, to +determine if the code that you received from the APR function means EOF, you +would use the macro APR_STATUS_IS_EOF().

+ +

Why did APR take this approach? There are two ways to deal with error +codes portably.

+ +
    +
  1. Return the same error code across all platforms. +
  2. Return platform specific error codes and convert them when necessary. +
+ +

The problem with option number one is that it takes time to convert error +codes to a common code, and most of the time programs want to just output +an error string. If we convert all errors to a common subset, we have four +steps to output an error string:

+ +

The second problem with option 1, is that it is a lossy conversion. For +example, Windows and OS/2 have a couple hundred error codes, but POSIX errno +only defines about 50 errno values. This means that if we convert to a +canonical error value immediately, there is no way for the programmer to +get the actual system error.

+ +
+    make syscall that fails
+        convert to common error code                 step 1
+        return common error code
+            check for success
+            call error output function               step 2
+                convert back to system error         step 3
+                output error string                  step 4
+
+ +

By keeping the errors platform specific, we can output error strings in two +steps.

+ +
+    make syscall that fails
+        return error code
+            check for success
+            call error output function               step 1
+                output error string                  step 2
+
+ +

Less often, programs change their execution based on what error was returned. +This is no more expensive using option 2 than it is using option 1, but we +put the onus of converting the error code on the programmer themselves. +For example, using option 1:

+ +
+    make syscall that fails
+        convert to common error code
+        return common error code
+            decide execution based on common error code
+
+ +

Using option 2:

+ +
+    make syscall that fails
+        return error code
+            convert to common error code (using ap_canonical_error)
+            decide execution based on common error code
+
+ +

Finally, there is one more operation on error codes. You can get a string +that explains in human readable form what has happened. To do this using +APR, call ap_strerror().

+ diff --git a/docs/canonical_filenames.html b/docs/canonical_filenames.html new file mode 100644 index 0000000..c1c03b1 --- /dev/null +++ b/docs/canonical_filenames.html @@ -0,0 +1,156 @@ + +APR Canonical Filenames + +

APR Canonical Filename

+ +

Requirements

+ +

APR porters need to address the underlying discrepancies between +file systems. To achieve a reasonable degree of security, the +program depending upon APR needs to know that two paths may be +compared, and that a mismatch is guaranteed to reflect that the +two paths do not return the same resource

. + +

The first discrepancy is in volume roots. Unix and pure derivatives +have only one root path, "/". Win32 and OS2 share root paths of +the form "D:/", D: is the volume designation. However, this can +be specified as "//./D:/" as well, indicating D: volume of the +'this' machine. Win32 and OS2 also may employ a UNC root path, +of the form "//server/share/" where share is a share-point of the +specified network server. Finally, NetWare root paths are of the +form "server/volume:/", or the simpler "volume:/" syntax for 'this' +machine. All these non-Unix file systems accept volume:path, +without a slash following the colon, as a path relative to the +current working directory, which APR will treat as ambiguous, that +is, neither an absolute nor a relative path per se.

+ +

The second discrepancy is in the meaning of the 'this' directory. +In general, 'this' must be eliminated from the path where it occurs. +The syntax "path/./" and "path/" are both aliases to path. However, +this isn't file system independent, since the double slash "//" has +a special meaning on OS2 and Win32 at the start of the path name, +and is invalid on those platforms before the "//server/share/" UNC +root path is completed. Finally, as noted above, "//./volume/" is +legal root syntax on WinNT, and perhaps others.

+ +

The third discrepancy is in the context of the 'parent' directory. +When "parent/path/.." occurs, the path must be unwound to "parent". +It's also critical to simply truncate leading "/../" paths to "/", +since the parent of the root is root. This gets tricky on the +Win32 and OS2 platforms, since the ".." element is invalid before +the "//server/share/" is complete, and the "//server/share/../" +sequence is the complete UNC root "//server/share/". In relative +paths, leading ".." elements are significant, until they are merged +with an absolute path. The relative form must only retain the ".." +segments as leading segments, to be resolved once merged to another +relative or an absolute path.

+ +

The fourth discrepancy occurs with acceptance of alternate character +codes for the same element. Path separators are not retained within +the APR canonical forms. The OS filesystem and APR (slashed) forms +can both be returned as strings, to be used in the proper context. +Unix, Win32 and Netware all accept slashes and backslashes as the +same path separator symbol, although unix strictly accepts slashes. +While the APR form of the name strictly uses slashes, always consider +that there could be a platform that actually accepts slashes as a +character within a segment name.

+ +

The fifth and worst discrepancy plagues Win32, OS2, Netware, and some +filesystems mounted in Unix. Case insensitivity can permit the same +file to slip through in both it's proper case and alternate cases. +Simply changing the case is insufficient for any character set beyond +ASCII, since various dialectic forms of characters suffer from one to +many or many to one translations. An example would be u-umlaut, which +might be accepted as a single character u-umlaut, a two character +sequence u and the zero-width umlaut, the upper case form of the same, +or perhaps even a capital U alone. This can be handled in different +ways depending on the purposes of the APR based program, but the one +requirement is that the path must be absolute in order to resolve these +ambiguities. Methods employed include comparison of device and inode +file uniqifiers, which is a fairly fast operation, or querying the OS +for the true form of the name, which can be much slower. Only the +acknowledgement of the file names by the OS can validate the equality +of two different cases of the same filename.

+ +

The sixth discrepancy, illegal or insignificant characters, is especially +significant in non-unix file systems. Trailing periods are accepted +but never stored, therefore trailing periods must be ignored for any +form of comparison. And all OS's have certain expectations of what +characters are illegal (or undesirable due to confusion.)

+ +

A final warning, canonical functions don't transform or resolve case +or character ambiguity issues until they are resolved into an absolute +path. The relative canonical path, while useful, while useful for URL +or similar identifiers, cannot be used for testing or comparison of file +system objects.

+ +
+ +

Canonical API

+ +Functions to manipulate the apr_canon_file_t (an opaque type) include: + + + +

The path is corrected to the file system case only if is in absolute +form. The apr_canon_file_t should be preserved as long as possible and +used as the parent to create child entries to reduce the number of expensive +stat and case canonicalization calls to the OS.

+ +

The comparison operation provides that the APR can postpone correction +of case by simply relying upon the device and inode for equivalence. The +stat implementation provides that two files are the same, while their +strings are not equivalent, and eliminates the need for the operating +system to return the proper form of the name.

+ +

In any case, returning the char* path, with a flag to request the proper +case, forces the OS calls to resolve the true names of each segment. Where +there is a penalty for this operation and the stat device and inode test +is faster, case correction is postponed until the char* result is requested. +On platforms that identify the inode, device, or proper name interchangably +with no penalties, this may occur when the name is initially processed.

+ +
+ +

Unix Example

+ +

First the simplest case:

+ +
+Parse Canonical Name 
+accepts parent path as canonical_t
+        this path as string
+
+Split this path Segments on '/'
+
+For each of this path Segments
+  If first Segment
+    If this Segment is Empty ([nothing]/)
+      Append this Root Segment (don't merge)
+      Continue to next Segment
+    Else is relative
+      Append parent Segments (to merge)
+      Continue with this Segment
+  If Segment is '.' or empty (2 slashes)
+    Discard this Segment
+    Continue with next Segment
+  If Segment is '..'
+    If no previous Segment or previous Segment is '..'
+      Append this Segment
+      Continue with next Segment
+    If previous Segment and previous is not Root Segment
+      Discard previous Segment
+    Discard this Segment
+    Continue with next Segment
+  Append this Relative Segment
+  Continue with next Segment        
+
+ + + diff --git a/docs/doxygen.conf b/docs/doxygen.conf new file mode 100644 index 0000000..29c2cbf --- /dev/null +++ b/docs/doxygen.conf @@ -0,0 +1,38 @@ +PROJECT_NAME="Apache Portable Runtime" + +INPUT=. +QUIET=YES +RECURSIVE=YES +FILE_PATTERNS=*.h + +OUTPUT_DIRECTORY=docs/dox + +MACRO_EXPANSION=YES +EXPAND_ONLY_PREDEF=YES +#EXPAND_AS_DEFINED= +# not sure why this doesn't work as EXPAND_AS_DEFINED, it should! +PREDEFINED="APR_DECLARE(x)=x" \ + "APR_DECLARE_NONSTD(x)=x" \ + "APR_DECLARE_DATA" \ + "APR_POOL_DECLARE_ACCESSOR(x)=apr_pool_t* apr_##x##_pool_get (const apr_##x##_t *the##x)" \ + "APR_DECLARE_INHERIT_SET(x)=apr_status_t apr_##x##_inherit_set(apr_##x##_t *the##x)" \ + "APR_DECLARE_INHERIT_UNSET(x)=apr_status_t apr_##x##_inherit_unset(apr_##x##_t *the##x)" \ + "APR_HAS_THREADS" \ + "__attribute__(x)=" \ + DOXYGEN= + +OPTIMIZE_OUTPUT_FOR_C=YES +STRIP_CODE_COMMENTS=NO + +FULL_PATH_NAMES=NO +CASE_SENSE_NAMES=NO +# some autoconf guru needs to make configure set this correctly... +# in the meantime, simply listing the headers should be alright +#STRIP_FROM_PATH=/buildpath/apr + +EXCLUDE_PATTERNS="*/acconfig.h" \ + "*/test/*" \ + "*/arch/*" + +GENERATE_TAGFILE=docs/dox/apr.tag + diff --git a/docs/incomplete_types b/docs/incomplete_types new file mode 100644 index 0000000..08b0c0a --- /dev/null +++ b/docs/incomplete_types @@ -0,0 +1,84 @@ +The question has been asked multiple times, "Why is APR using Incomplete +types?" This document will try to explain that. + +Incomplete types are used in APR because they can enforce portability, and +they make the APR developers job easier, as well as allowing APR to use native +types on all platforms. Imagine a scenario where APR wasn't using incomplete +types. The ap_file_t type would have to be defined as: + +typedef struct ap_file_t { + ap_pool_t *pool + char *fname; + int eof_hit; + int pipe; + ap_interval_time_t timeout; +#ifdef WIN32 + HANDLE file_handle; + DWORD dwFileAttributes; +#elif defined(OS2) + HFILE filedes; + HEV PipeSem +#else + int filedes; + int ungetchar; +#endif + +#ifndef WIN32 + int buffered; + ap_int32_flags + int isopen; + + /* Stuff for buffered mode */ + char *buffer; + int bufpos; + unsigned long dataRead; + int direction; + unsigned long filePtr; + ap_lock_t *mutex; +#endif +} ap_file_t; + +This captures the essence of what is currently being defined for ap_file_t +using incomplete types. However, using this structure leads developers to +believe that they are safe accessing any of the fields in this structure. +This is not true. On some platforms, such as Windows, about half of the +structure disappears. We could combine some of these definitions with +macros, for example: + +#ifdef WIN32 +#define filetype HANDLE +#elif OS2 +#define filetype HFILE +#else +#define filetype int +#endif + +And then in the definition for ap_file_t, we could say: + filetype filedes; + +This gets rid of some of the complexity, by moving it off to the side, but +it is still not safe for a programmers to access the filedes field directly +outside of APR, because the programmer has no way of knowing what the actual +type is. So for example printing the filedes using printf would yield wildly +varying results on Windows and OS2 when compared to Unix. + +Another option also presents itself. Stick strictly to POSIX. This means +that all code can be shared on any POSIX compliant platform. The problem +with this is performance. One of the benefits to APR, is that it allows +developers to easily use native types on all platforms with the same code. +This has proven to provide a substantial performance boost on most non-Unix +platforms. + +Having said all of that, sometimes incomplete types just don't make sense. +For example, the first implementation of time functions used incomplete types, +which added a layer of complexity that turned out to be unnecessary. If +a platform cannot provide a simple number that represents the number of seconds +elapsed since a specified date and time, then APR doesn't really want to +provide support for that platform. + +APR is trying hard to provide a balance of incomplete and complete types, +but like all things, sometimes the developers make mistakes. If you are +using APR and find that there is an incomplete type that doesn't need to be +an incomplete type, please let us know, we are more than willing to listen +and design parts of APR that do not use incomplete types. + diff --git a/docs/non_apr_programs b/docs/non_apr_programs new file mode 100644 index 0000000..5003a8b --- /dev/null +++ b/docs/non_apr_programs @@ -0,0 +1,47 @@ +How do I use APR'ized programs in connection with programs that don't +use APR? These darn incomplete types don't let me fill out the APR types. + +The APR developers acknowledge that most programs are not using APR, and +we don't expect them to migrate to using APR just because APR has been +released. So, we have provided a way for non-APR'ized programs to interact +very cleanly with APR. + +There are a set of functions, all documented in apr_portable.h, which allow +a programmer to either get a native type from an APR type, or to setup an +APR type from a native type. + +For example, if you are writing an add-on to another program that does not use +APR for file I/O, but you (in your infinite wisdom) want to use APR to make +sure your section is portable. Assume the program provides a type foo_t with +a file descriptor in it (fd). + +void function_using_apr(foo_t non_apr_struct, ap_pool_t *p) +{ + ap_file_t *apr_file = NULL; + + ap_put_os_file(&apr_file, &non_apr_struct->fd, p); + + ... +} + +There are portable functions for each APR incomplete type. They are all +called ap_put_os_foobar(), and they each take the same basic arguments, a +pointer to a pointer to the incomplete type (the last pointer in that list +should be NULL), a pointer to the native type, and a pool. Each of these can +be found in apr_portable.h. + +If you have to do the exact opposite (take an APR type and convert it to a +native type, there are functions for that too. For example: + +void function_not_using_apr(apr_file_t *apr_file) +{ + int unix_file_desc; + + ap_get_os_file(&unix_file_desc, apr_file); + + ... +} + +For each ap_put_os_foobar, there is a corresponding ap_get_os_file. These are +also documented in apr_portable.h. + diff --git a/docs/pool-design.html b/docs/pool-design.html new file mode 100644 index 0000000..46b63d6 --- /dev/null +++ b/docs/pool-design.html @@ -0,0 +1,96 @@ + + + Using APR Pools + + +

Using APR Pools

+ +

+ From Subversion, we + have learned a lot about how to use pools in a heavily + structured/object-based environment. + Apache httpd is a + completely different beast: "allocate a request pool. use + it. destroy it." +

+ +

+ In a complex app, that request-style of behavior is not + present. Luckily, the "proper" use of pools can be described in + just a few rules: +

+ + + +
+
Greg Stein
+ + +Last modified: Wed Jun 25 14:50:19 PDT 2003 + + + diff --git a/docs/win32_builds.html b/docs/win32_builds.html new file mode 100644 index 0000000..ad57d8e --- /dev/null +++ b/docs/win32_builds.html @@ -0,0 +1,57 @@ + +APR Win32 Builds and Debugging + +

APR Win32 Builds and Debugging

+ +

Configuration and Flavors

+ +

The Win32 APR Developer Studio projects consist of

+ +
+
apr/apr.dsp
+
Builds the static apr.lib library (-D APR_DECLARE_STATIC)
+
apr/libapr.dsp
+
Builds the dynamic libapr.dll library (no define required)
+
apr-util/aprutil.dsp
+
Builds the static aprutil.lib library (-D APU_DECLARE_STATIC)
+
apr-util/libaprutil.dsp
+
Builds the dynamic libaprutil.dll library (no define required)
+
apr-iconv/apriconv.dsp
+
Builds the static apriconv.lib library (-D API_DECLARE_STATIC)
+
apr-iconv/libapriconv.dsp
+
Builds the dynamic libapriconv.dll library (no define required)
+
+ +

In order to prepare to use one of the static libraries above, + your application must be compiled with the define shown above, so that the + correct linkage is created. The APR authors intended the use of dynamic + libraries by default, so application authors do not need any special + defines in order to link to the dynamic library flavors.

+ +

In order to build APR, you must use the proper dependencies. A good + example of those dependencies is given in the apr-util/aprutil.dsw + Developer Studio workspace. You can borrow the parts of that structure + your application needs, that workspace defines both the dynamic and static + library dependencies.

+ +

The APR libraries (dynamic and static) are compiled with debugging symbols, + even in Release builds. The dynamic library symbols are always usable, + simply keep the correspond .pdb file in the same path as the library .dll. + (E.g. both libapr.dll and libapr.pdb should be copied to the same path.)

+ +

The static symbols will only be fully usable if your application does not + link with the /pdbtype:sept flag! At the time your application links to + an APR library, the corresponding _src.pdb file should exist in the original + path the library was built, or it may be sufficient to keep the _src.pdb file + in the same path as the library file. (E.g. apr.lib and apr_src.pdb should + reside together in your lib directory.) The later option is unconfirmed.

+ +

In order to keep the symbols compiled into the static library, your application + must use the linker's /debug flag. If you do not want the application to be + debuggable with its corresponding .pdb file, omit the /debug flag and all debug + symbolic information is discarded. Note that your application can only be + debugged with the corresponding .pdb file created by the linker, unless you use + /debugtype:coff or /debugtype:both in your link options.

+ + + -- cgit v1.2.3