NAME

    Charmonizer - Use C to configure C.

OVERVIEW

    Charmonizer is a tool for probing, normalizing, and testing the build
    environment provided by a C compiler and an operating system.  It works by
    attempting to compile lots of little programs and analyzing the output
    from those that build successfully.  `
    
    Charmonizer modules are ordinary ANSI C files, and the configuration
    application that you write is an ordinary C executable.  
    
REQUIREMENTS

    Charmonizer's only prerequisite is an ISO C90-compliant compiler which can
    be invoked from C via the system() command.  The build system assumes you
    have a corresponding make or nmake executable.  Folks hacking on the Charmonizer
    source need to be aware of  ../devel/bin/gen_charmonizer_makefiles.pl which
    generates the makefiles from the src tree.
    
PROBING

        #include "Charmonizer/Probe.h"
        #include "Charmonizer/Probe/Integers.h"
        #include "Charmonizer/Probe/LargeFiles.h"

        int main() 
        {
            /* Tell Charmonizer about your OS and compiler. */
            chaz_Probe_init("cc", "-I/usr/local/include", NULL);
            
            /* Run desired Charmonizer modules. */
            chaz_Integers_run();
            chaz_LargeFiles_run();

            /* Tear down. */
            chaz_Probe_clean_up();

            return 0;
        }

    The purpose of Charmonizer's probing toolset is to generate a single C
    header file called "charmony.h", gathering together information that is
    ordinarily only available at runtime and assigning predictable names to
    functionality which may go by many different aliases on different systems.

    One header file, "Charmonizer/Probe.h", provides the primary interface and
    a suite of topically oriented modules -- e.g.
    "Charmonizer/Probe/LargeFiles.h", "Charmonizer/Probe/Integers.h" -- do the
    heavy lifting.  Each topical module exports 1 main function,
    ModuleName_run(), which runs all the relevant compiler probes and appends
    output to charmony.h.  As you run each module in turn, "charmony.h" gets
    built up incrementally; it can be further customized by writing your own
    content to it at any point.

TESTING 

    #include "Charmonizer/Test.h"
    #include "Charmonizer/Test/Integers.h"
    #include "Charmonizer/Test/Largefile.h"
    #include "MyTest.h"

    int main() {
        int all_tests_pass = 0;

        /* Set up. */
        chaz_Test_init();
        chaz_Integers_init_test();
        chaz_LargeFiles_init_test();
        MyTest_init_test();

        /* Run all the tests */
        all_tests_pass = chaz_Test_run_all_tests();

        /* Tear down. */
        chaz_Test_clean_up();

        return all_tests_pass;
    }

    Charmonizer provides both a general test harness for writing your own
    tests, and a corresponding test module for each probing module. The stock
    tests can be found within "Charmonizer/Test" -- e.g. at
    "Charmonizer/Test/Integers.h".  
    
    The stock tests require access to "charmony.h".  Not all tests will pass
    in every environment, and the expectation is that you will append
    charmony.h with ifdef tests as necessary to draw in supplementary code:

        #ifndef HAS_DIRENT_H
          #include "my/dirent.h"
        #endif

    Charmonizer restricts itself to working with what it finds, and
    does not supply a library of compatibility functions.

C NAMESPACE

    The "charmony.h" header prepends a prefix onto most of the symbols it
    exports: either "chy_" or "CHY_".  For public code, such as header files,
    this helps avoid namespace collisions.  For private code, the prefixes can
    be stripped via the CHY_USE_SHORT_NAMES symbol.

        #define CHY_USE_SHORT_NAMES
        #ifdef HAS_LONG_LONG   /* alias for CHY_HAS_LONG_LONG */

FILESYSTEM NAMESPACE

    Charmonizer creates a number of temporary files within the current working
    directory while it runs.  These files all begin with "_charm".