windows-server-2003/admin/burnslib/readme.txt

Copyright (c) 1997-2001 Microsoft Corporation

BURNSLIB: Basic Utility Resource 'N String Library ;->
==================================================

There are two flavors of this library: the "core" and the "rest."

The core library is the most stable, and most easily used in just about any
application.  It consists of the following:

    - class String, which is a Windows-aware, enhancement of std::wstring.

    - Replacement versions of ::operator new and ::operator delete,
      which, among other things allow each allocation to be accompanied
      with file, line number and stack trace at the point of allocation.

    - class Log, which provides thread-safe diagnostic logging with
      output directable to debugger, file, a named pipe.

    - A very small set of lightweight COM helpers which do not exhibit
      the elephantine nature of MFC and ATL constructs of similar
      purpose.

The rest is really meant for my own use, but has since garnered enough
dependent projects that we have to take version control serviously (the
bane of the shared code author).

IMPORTANT:

If you use the core or the rest, please update the dependents.txt file so
that I can make sure changes I make don't break your build.



To use the core library in your code:
====================================

In your razzle environment (for chk builds, this causes the linker to use
the debug CRT .lib files and passes -D_DEBUG to the compiler.  This is
necessary to use the heap debugging functionality)

    set DEBUG_CRTS=1

In your headers.hxx file
    
    Add #include <blcore.hpp> before any headers for code that you want to
    use the replacement operator new and delete.  (Generally, I only put
    include headers from outside my project in headers.hxx.  So, I include
    blcore.hpp last in my headers.hxx.)

    Note that blcore.hpp #includes syscore.hpp, which in turn #includes
    several sdk header files.  You may want to remove redundant inclusion
    of those files.

In your sources file:

    Add admin\burnslib\inc to the INCLUDES macro

    Add the following to your UNLIBS or TARGETLIBS macro
        $(SDXROOT)\admin\burnslib\lib\*\blcore.lib

    Add the following lines:

        # enable logging for chk builds

        !if !$(FREEBUILD)
        !MESSAGE defining LOGGING_BUILD
        C_DEFINES=$(C_DEFINES) -DLOGGING_BUILD
        !ENDIF

        # enable Unicode support

        C_DEFINES=$(C_DEFINES) -DUNICODE -D_UNICODE

        # enable C++ Standard Template Library

        USE_STL=1

        # enable C++ Exceptions

        USE_NATIVE_EH=1

        # use msvcrt (C runtimes)

        USE_MSVCRT=1

Somewhere in your source code, you need to define the following symbols.
See blcore.hpp for explanations of each.

        HINSTANCE hResourceModuleHandle
        const wchar_t* RUNTIME_NAME
        DWORD DEFAULT_LOGGING_OPTIONS

In your project's resource script (rc) file, #include blcore.rc.  These are
the resources for the out-of-memory dialog.



Notes:
=========================
    
Since you are using the debug CRTs, you will need to have available on your
search path msvcrtd.dll and possibly also msvcp50d.dll (depending on which
STL templates your code uses).  This means that you will may need to
include those dlls with any private chk binaries you distribute.

All of BURNSLIB compiles clean with warning level 4, so you can include
MSC_WARNING_LEVEL=/W4 in your sources if you wish.

BURNSLIB is statically linked to your binary.  There is no associated dll.

It replaces the global operator new, operator new[], operator delete, and
operator delete[] with private versions.  This isolates the behavior of
those operators to your binary.  To understand why this is a Good Thing,
see new.doc.  If you use STL template classes, then remember to use the
Burnslib::Heap::Allocator classes to keep the STL from falling back to the
CRT allocator.

If you plan to use any functions that load resources (strings, icons,
etc.), you need to make sure you set the hResourceModuleHandle to the
HINSTANCE of the binary containing the resource.  The best place to do this
is the first line of code in WinMain/DllMain.  The design of the library
assumes that all resources are in the same binary; a tradeoff between
simplicity and flexibility.  In your code, you can retrieve this handle by
calling Burnslib::GetResourceModuleHandle().

Most of the symbols are in the Burnslib namespace.  blcore.hpp specifies
"using namespace Burnslib;" so you don't have to.



To use the "rest" of the library in your code:
=============================================

Cut and paste.  Don't link directly to it.  I tweak the rest with reckless
abandon and will offer no apologies for breaking your code.

Well, that was then.  I will try to be a good citizen here.

<eof>