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>