Differences between revisions 15 and 16
Revision 15 as of 2006-05-11 04:00:44
Size: 11275
Editor: 101-18
Revision 16 as of 2009-09-20 23:35:36
Size: 11259
Editor: localhost
Comment: converted to 1.6 markup
Deletions are marked like this. Additions are marked like this.
Line 8: Line 8:
Name: Walter Mundt [[BR]]
Email: emage@spamcop.net [[BR]]
Cell Phone: 1-407-782-3491 [[BR]]
Apache SoC Subject ID: [wiki:Self:
SummerOfCode2006#apr-build-system apr-build-system] [[BR]]
Name: Walter Mundt <<BR>>
Email: emage@spamcop.net <<BR>>
Cell Phone: 1-407-782-3491 <<BR>>
Apache SoC Subject ID:
[[SummerOfCode2006#apr-build-system|apr-build-system]] <<BR>>
Line 39: Line 39:
[[Anchor(apr-logging)]] <<Anchor(apr-logging)>>
Line 42: Line 42:
Subject ID: [wiki:Self:SummerOfCode2006#apr-logging apr-logging] Subject ID: [[SummerOfCode2006#apr-logging|apr-logging]]

Proposals for SummerOfCode2006


Submitted Improve the APR build system

Name: Walter Mundt
Email: emage@spamcop.net
Cell Phone: 1-407-782-3491
Apache SoC Subject ID: apr-build-system
Title: Improve the APR build system

General Experience

I am a good generalist programmer with knowledge of many programming languages and techniques. I competed in the ACM International Collegiate Programming Contest finals this year. Languages with which I am very familiar include C/C++, Python, Java, Perl, and sh script. I've also dabbled in Lisp, C#, VB, among others. I also understand Linux system administration - I have RHCE certification. I also have a bit of OSS experience: I acted as a "core team" development person for the TWiki project (twiki.org) for a while, and have submitted patches here and there wherever I ended up fixing/improving something open source.


Ever since learning Python I find it very pleasant to develop in. Additionally, this task seems well-defined and will benefit from my contest experience, where text manipulation/generation problems are fairly common. Finally, as a user of both Apache and Subversion, it appeals to me to do work on improving a component used by both.


The primary deliverable should be a patch to add Win32 and Netware build support to the build/gen-build.py. Support for additional build systems may be added as time and available test environments allow for the duration of the SummerOfCode. Documentation of any new options/usage scenarios for the gen-build.py script will also be included. Note that I do NOT have access to a Netware development environment, so others will have to test the Netware build system changes.

New Features

Once the enhanced build-gen is working for selecting the source files to compile, some new features should be added for making the builds on the newly-supported platforms as configurable as Unix builds. Primarily, this will involve reimplementing the linkage-level choices made by autoconf within the gen-build.py script, or (where support exists) into the actual generated build files.


The first step will be to attempt to have the script generate results as close as possible to the current, working build files for the new platforms it will support. The resulting build files should be tested on as many variants of the target platform as possible, and it should be shown that they will remain correct when source files are added/removed/renamed in the gen-build-managed directories.

Once that's working, add and document additional options in gen-build for enabling and diabling optional libraries; these options and their effects might be configured in build.conf. On Windows, consider adding a third option for each library that generates duplicate "configuration" entries in the DSP for an option, one set w/the library in and one set without.

Open Questions

As I understand things, the gen-build.py script is currently run pre-distribution by the library developers. If this is the case, being able to use the script to change linkage options would add a new build dependency for Python on Windows platforms. Is this an issue for anyone? If it is, should the "third option" discussed above be prioritized more, since it partially alleviates this issue by allowing library users to make the most common linkage choices within the IDE without having to re-run gen-build?

Post-SoC Intentions

Should I be selected to work on this during the SoC, I will also, at the least, commit to maintaining my changes over the 6-8 months following, or until any major issues are resolved, whichever is longer. If I really enjoy working with this, or if there is a lot of demand, I may go further and keep adding features.

Add basic logging capabilities to APR

Subject ID: apr-logging



  • This design is very much open to debate by the community, both now and during development if this application is accepted.
  • Requiring the user to provide a file pointer provides fine-grained control over things like overwrite/append, log permissions, etc.
  • Level granularity
    • The Windows Event log's "level" resolution is very low -- Error/Warning/Info
      • Perhaps use a special APR "message file" with categories for the rest?
    • Linux syslog, OTOH, has ~8 levels
  • Dates
    • times and dates are very useful in logs, but performance may also be a concern, so access options to use both strftime-based date information, and the apr_time fast rfc822 and ctime implementations is provided.
  • used_fallback could be a return status code. It might be different from the return of apr_log_is_system if a system logging implementation is made for an OS-dependent logger that does not add level and date information to logs on its own.

  • Thread-safety: A single apr_log_t instance must not have multiple apr_log_* functions called on it simultaneously by different threads; this code should otherwise be completely thread-safe.

  • Access to the Windows "event source"/"event category" API is currently limited to using predefined sets of sources and categories analogous to Unix syslog facilities and severity levels. However, since there's no mechanism of equivalent or greater expressiveness on any other platform, this was deemed acceptable.


  • apr_log_t - Type for a log destination


  • Log level constants - each level is a bit
  • Facility constants - equivalent to syslog constants on platforms with syslog, same names on Windows using special "APR" event source, automatically generated on first call to apr_log_open_system (note: this will require autodetection of the path to the APR DLL, which will have to be build with a special Windows "message file" defining the syslog facilities)


  • apr_log_open_system(apr_log_t **newlog, int **used_fallback, apr_int32_t level_mask, apr_file_t *fallback, apr_pool_t *pool) -- Opens a log destination for the system default logger, using the system-dependent implementation if one is available, and falling back to writing to the provided file if one is not. For convenience, if fallback is NULL and a fallback is needed, falls back to stderr logging. used_fallback will be set if the fallback file or stderr is used.

  • apr_log_open_file(apr_log_t **newlog, apr_file_t *file, apr_int32_t level_mask, apr_pool_t *pool) -- Opens a log destination which will write to the specified APR file object.

  • apr_log_set_buffer(apr_log_t *log, char *buf, apr_int32_t size) -- Set this log's internal buffer. This function must be called before using apr_log on a log instance.

  • apr_log_is_system(apr_log_t *log) -- Returns (with what values?) whether the log is a system-dependent logger that automatically adds date/time and level information to log messages, so that those can be excluded from the format string if desired.

  • apr_log_set_format(apr_log_t *log, const char *format, int use_strftime) -- Sets the format string, which is a literal string except for the following codes:

    • $m -- log message

    • $l -- log level as a string

    • $L -- log level as a number (useful? may not go in)

    • $f -- log facility as a string

    • $$ -- literal $

    • $d -- RFC822 date

    • $D -- ctime() date

    • $t -- raw apr_time_t value

    • %* -- _if_ use_strftime is true, any strftme code may be used as well

  • apr_log_set_level_mask(apr_log_t *log, apr_int32_t level_mask) -- Sets the level mask of the log -- calls to apr_log_write where (level_mask & level) is false will be ignored. The initial level mask is set in the log constructor.

  • apr_log_set_facility(apr_log_t *log, apr_int32_t facility) -- set facility used for messages, default APR_LOG_USER

  • apr_log_write(apr_log_t *log, apr_int32_t level, const char *message, apr_pool_t *pool) -- Writes a log entry using the current format. The default format if apr_log_set_format has not been set is "$m" for loggers where apr_log_is_system is true, and "[$d] $l: $m" otherwise.

  • apr_log(apt_log_t *log, apr_int32_t level, const char *messageTemplate, ...) -- Calls apr_vsnprintf to generate a log message in this log's internal buffer and then immediately calls apr_log_write on said buffer, or does something functionally equivalent.

  • Getter functions matching apr_log_set_*.


  • A new header file (probably apr-logging.h) defining the new logging API

  • Platform-independent file-based logging implementation
  • A new platform-specific subdirectory (probably logging/{unix,win32,...} ) implementing the API

    • Unix syslog implementation
    • Windows Event Logger implementation
    • Others if access to test/development systems and pointers to API docs are provided
  • A new test/testlogging.c test suite.

  • Changes to the global APR docs/ as necessary to reflect the presence of the new API

  • Adjustments to build.conf and the other build files to build the new code

All code is to be documented inline according to APR standard practice.


First, the header file should be written according to the design. Then, start with the test suite and basic "write to a log file"/"write to console" logger implementations. Once those are working fine, add the Unix syslog implementation and Windows Event Logger implementations.

Development will occur on Linux and Windows to begin with. On the Linux side, GCC 3.2 and 4.0 are planned as during-development targets; on Windows, cygwin's GCC, Dev-C++'s mingw runtime, and VS6 are all planned targets. Once development reaches a usable alpha state, patches will be distributed so that anyone running other platforms can test for portability issues; distribution method(s) to be negotiated -- manual mailing-list posts, daily snapshots on the Web, and svn branch commits are all (non-mutually exclusive) options.

Post-SoC Intentions

Should I be selected to work on this during the SoC, I will also, at the least, commit to maintaining my changes over the 6-8 months following, or until any major issues are resolved, whichever is longer. If new features are widely demanded by the community, I will very likely implement them. Aside from that, if I really like working with APR I may go on to work on other parts of it, as I don't think a logging API as basic as what I have described here will need much work after the summer is over. I also don't think a more elaborate system (think "log4c") would be a good fit for being part of APR itself.

WalterMundt/SummerOfCodeProposals (last edited 2009-09-20 23:35:36 by localhost)