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

    The only prerequisite for the target machine is an ISO C90-compliant
    compiler which can be invoked from C via the system() command.  Your
    development environment must include Perl in order to run the metaquote 
    utility script, but no Perl programming is required.
    
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("darwin", "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 module exports 1 main function, ModuleName_run(),
    which appends output to charmony.h. The config gets built up bit by bit as
    you run each module in turn.  "charmony.h" can be further customized by
    writing your own content to it.

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.
    (Charmonizer restricts itself to working with what it finds, and
    does not supply a library of compatibility functions.)

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

C NAMESPACE

    Charmonizer allows you to prepend a prefix onto every symbol it exports.
    For public code, such as header files, this helps avoid namespace
    collisions.  For private code, the prefixes are stripped via
    the USE_SHORT_NAMES symbol.

        #ifdef LUCY_HAS_LONG_LONG
            /* ... */
        #define LUCY_USE_SHORT_NAMES
        #ifdef 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".

GATHERING FILES

    Charmonizer master modules are stored in the src/ directory, and have
    .harm/.charm extensions.  They are ordinary ANSI C files, except for one
    thing: multi-line quoted snippets of source code are surrounded by
    "METAQUOTE" tags.  This is done for maintainability's sake, since
    embedding C source code in C source code as string literals is very messy.

    To generate all the necessary Charmonizer .c/.h files, use the metaquote 
    utility.

        $ ./bin/metaquote --src=/path/to/charmonizer/src --out=/my/charm/dir 

SECURITY

    Under no circumstances should input from untrusted users be supplied to
    Charmonizer.  A lot of what it does it does by passing strings to the
    system() command.  

COPYRIGHT AND LICENSE

    /**
     * Copyright 2006 The Apache Software Foundation
     *
     * Licensed under the Apache License, Version 2.0 (the "License");
     * you may not use this file except in compliance with the License.
     * You may obtain a copy of the License at
     *
     *     http://www.apache.org/licenses/LICENSE-2.0
     *
     * Unless required by applicable law or agreed to in writing, software
     * distributed under the License is distributed on an "AS IS" BASIS,
     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
     * implied.  See the License for the specific language governing
     * permissions and limitations under the License.
     */