README
1Apache Portable Runtime Utility Library README
2----------------------------------------------
3
4 The Apache Portable Runtime Utility Library provides a predictable
5 and consistent interface to underlying client library interfaces.
6 This API assures predictable if not identical behavior regardless
7 of which libraries are available on a given platform.
8
9 APR and its companion libraries are implemented entirely in C
10 and provide a common programming interface across a wide variety
11 of operating system platforms without sacrificing performance.
12 Currently supported platforms include:
13
14 UNIX variants
15 Windows
16 Netware
17 Mac OS X
18 OS/2
19
20 To give a brief overview, the primary core
21 subsystems of APR-util 1.3 include the following:
22
23 Hashing and UUID services
24 Multiple SQL DBD client interfaces
25 Multiple flat-database DBM client interfaces
26 Typesafe function Hooks abstraction
27 LDAP SSL connections for a variety of LDAP toolkits
28 MemCache interface
29 Date parsing rourtines
30 Resource Lists
31 Thread Pools
32 Queues
33 Relocatable Memory Management functions
34 String filename-style pattern matching
35 URI Parsing
36 Charset translation (iconv based)
37 XML parsing (expat)
38
39 For a more complete list, please refer to the following URLs:
40
41 http://apr.apache.org/docs/apr-util/modules.html
42
43 Users of APR 0.9 should be aware that migrating to the APR 1.x
44 programming interfaces may require some adjustments; APR 1.x is
45 neither source nor binary compatible with earlier APR 0.9 releases.
46 Users of APR 1.x can expect consistent interfaces and binary backwards
47 compatibility throughout the entire APR 1.x release cycle, as defined
48 in our versioning rules:
49
50 http://apr.apache.org/versioning.html
51
52 APR is already used extensively by the Apache HTTP Server
53 version 2 and the Subversion revision control system, to
54 name but a few. We list all known projects using APR at
55 http://apr.apache.org/projects.html -- so please let us know
56 if you find our libraries useful in your own projects!
57
58
59Database Providers
60------------------
61As of apr-util version 1.2.11, MySQL DBD driver is shipped as part of the
62distribution. However, to avoid licensing incompatibilities, it is not
63built by default. To enable MySQL support, use the --with-mysql option,
64but be aware that the MySQL license may introduce licensing implications
65for your compiled code. Similarly, the bindings for propritary drivers
66such as Oracle (--with-oracle option) must also be explicitly enabled.
67
68On windows, selection of supported drivers is via the environment values
69DBD_LIST (for mysql, oracle, pgsql, sqlite2 and/or sqlite3)
70and DBM_LIST (db and/or gdbm). DBD odbc and DBM sdbm are unconditionally
71compiled and installed, do not include these in the list.
72
73Whenever distributing apr-util in combination with database client
74drivers, always review the license requirements of all components.
75
76
77Cryptographic Software Notice
78-----------------------------
79This distribution includes cryptographic software. The country in
80which you currently reside may have restrictions on the import,
81possession, use, and/or re-export to another country, of
82encryption software. BEFORE using any encryption software, please
83check your country's laws, regulations and policies concerning the
84import, possession, or use, and re-export of encryption software, to
85see if this is permitted. See http://www.wassenaar.org/ for more
86information.
87
88The U.S. Government Department of Commerce, Bureau of Industry and
89Security (BIS), has classified this software as Export Commodity
90Control Number (ECCN) 5D002.C.1, which includes information security
91software using or performing cryptographic functions with asymmetric
92algorithms. The form and manner of this Apache Software Foundation
93distribution makes it eligible for export under the License Exception
94ENC Technology Software Unrestricted (TSU) exception (see the BIS
95Export Administration Regulations, Section 740.13) for both object
96code and source code.
97
98The following provides more details on the included cryptographic
99software:
100
101 APR-Util provides an abstract interface for symmetrical cryptographic
102 functions that make use of a general-purpose encryption library,
103 such as OpenSSL, NSS, or the operating system's platform-specific
104 facilities. This interface is known as the apr_crypto interface,
105 with implementation beneath the /crypto directory.
106
107 APR-Util provides an abstract interface for SSL encrypted LDAP (ldaps
108 and STARTTLS style) connections, which can be powered by OpenLDAP,
109 Netscape LDAP SDK, Mozilla LDAP SDK, or other platform specific ldap
110 interfaces.
111
112
README.cmake
1Experimental cmake-based build support for APR-Util on Microsoft Windows
2
3Status
4------
5
6This build support is currently intended only for Microsoft Windows.
7Only Windows NT-based systems can be targeted. (The traditional
8Windows build support for APR can target Windows 9x as well.)
9
10This build support is experimental. Specifically,
11
12* It does not support all features of APR-Util.
13* Some components may not be built correctly and/or in a manner
14 compatible with the previous Windows build support.
15* Build interfaces, such as the mechanisms which are used to enable
16 optional functionality or specify prerequisites, may change from
17 release to release as feedback is received from users and bugs and
18 limitations are resolved.
19
20Important: Refer to the "Known Bugs and Limitations" section for further
21 information.
22
23 It is beyond the scope of this document to document or explain
24 how to utilize the various cmake features, such as different
25 build backends or provisions for finding support libraries.
26
27 Please refer to the cmake documentation for additional information
28 that applies to building any project with cmake.
29
30Prerequisites
31-------------
32
33The following tools must be in PATH:
34
35* cmake, version 2.8 or later
36 cmake version 3.1.3 or later is required to work with current OpenSSL
37 releases. (OpenSSL is an optional prerequisite of APR-Util.)
38* If using a command-line compiler: compiler and linker and related tools
39 (Refer to the cmake documentation for more information.)
40
41The following support libraries are mandatory:
42
43* APR 1.4.x or APR 1.5.x, built with cmake
44
45Optional support libraries allow optional features of APR to be enabled:
46
47* OpenSSL
48* many others potentially, though the build support isn't currently
49 implemented
50
51How to build
52------------
53
541. cd to a clean directory for building (i.e., don't build in your
55 source tree)
56
572. Some cmake backends may want your compile tools in PATH. (Hint: "Visual
58 Studio Command Prompt")
59
603. set CMAKE_LIBRARY_PATH=d:\path\to\prereq1\lib;d:\path\to\prereq2\lib;...
61
624. set CMAKE_INCLUDE_PATH=d:\path\to\prereq1\include;d:\path\to\prereq2\include;...
63
645. cmake -G "some backend, like 'NMake Makefiles'"
65 -DCMAKE_INSTALL_PREFIX=d:/path/to/aprinst
66 -DAPR-Util-specific-flags
67 d:/path/to/aprutilsource
68
69 If APR 1.x was installed to a different directory than APR-Util,
70 also pass these additional arguments:
71
72 -DAPR_INCLUDE_DIR=d:/path/to/apr1inst/include
73 -DAPR_LIBRARIES=d:/path/to/apr1inst/lib/libapr-1.lib
74
75 Alternately, use cmake-gui and update settings in the GUI.
76
77 APR-Util feature flags:
78
79 APU_HAVE_CRYPTO Build crypt support (only the OpenSSL
80 implementation is currently supported)
81 Default: OFF
82 APU_HAVE_ODBC Build ODBC DBD driver
83 Default: ON
84 APR_BUILD_TESTAPR Build APR-Util test suite
85 Default: OFF
86 TEST_STATIC_LIBS Build the test suite to test the APR static
87 library instead of the APR dynamic library.
88 Default: OFF
89 In order to build the test suite against both
90 static and dynamic libraries, separate builds
91 will be required, one with TEST_STATIC_LIBS
92 set to ON.
93 INSTALL_PDB Install .pdb files if generated.
94 Default: ON
95
96 CMAKE_C_FLAGS_RELEASE, _DEBUG, _RELWITHDEBINFO, _MINSIZEREL
97
98 CMAKE_BUILD_TYPE
99
100 For NMake Makefiles the choices are at least DEBUG, RELEASE,
101 RELWITHDEBINFO, and MINSIZEREL
102 Other backends make have other selections.
103
1046. build using chosen backend (e.g., "nmake install")
105
106Known Bugs and Limitations
107--------------------------
108
109* If include/apu.h or other generated files have been created in the source
110 directory by another build system, they will be used unexpectedly and
111 cause the build to fail.
112* Options should be provided for remaining features, along with finding any
113 necessary libraries
114 + DBM:
115 . APU_HAVE_GDBM
116 . APU_HAVE_NDBM
117 . APU_HAVE_DB
118 + DBD:
119 . APU_HAVE_PGSQL
120 . APU_HAVE_MYSQL
121 . APU_HAVE_SQLITE3
122 . APU_HAVE_SQLITE2
123 . APU_HAVE_ORACLE
124 + CRYPTO:
125 . APU_HAVE_NSS
126 + XLATE, APU_HAVE_ICONV (no way to consume an apr-iconv build yet)
127* Static builds of APR modules are not supported.
128* CHANGES/LICENSE/NOTICE is not installed, unlike Makefile.win.
129 (But unlike Makefile.win we want to call them APR-Util-CHANGES.txt
130 and so on.) But perhaps that is a job for a higher-level script.
131
132Generally:
133
134* Many APR-Util features have not been tested with this build.
135* Developers need to examine the existing Windows build in great detail and see
136 what is missing from the cmake-based build, whether a feature or some build
137 nuance.
138* Any feedback you can provide on your experiences with this build will be
139 helpful.
140
README.FREETDS
1The APR DBD Driver for FreeTDS has been removed from the build.
2It is known to have problems, and we are not able to maintain it.
3
4The source code is still available. If you want it and are able
5to manage maintenance for yourself, you can patch the build and
6work through issues that affect you, but you're on your own.
7
8We expect that for most users, the ODBC driver will serve as
9an alternative.
10
11Sorry.
12