From: Chris Koeritz Date: Thu, 16 Feb 2012 00:06:55 +0000 (-0500) Subject: moving documentation around into some kind of coherent non-mess, eventually. X-Git-Tag: 2.140.90~1603 X-Git-Url: https://feistymeow.org/gitweb/?p=feisty_meow.git;a=commitdiff_plain;h=eb6dc8f19d6bc48bd41e85028d4d214955d07829 moving documentation around into some kind of coherent non-mess, eventually. --- diff --git a/doc/bash_tools.html b/doc/bash_tools.html new file mode 100644 index 00000000..8a0dc853 --- /dev/null +++ b/doc/bash_tools.html @@ -0,0 +1,123 @@ + + + + + + + + + YETIcode Bash Scripts + + + + +

 

+
+ + + + + + +
+
+

YETIcode Open Source Bash +Scripts

+

GPL-Licensed Bash Code
+

+
+
Contributed by Chris Koeritz (Koeritz@Gruntose.COM)
+See the GNU Public +License for details of licensing.
+
+

Caveats: please refer to the Perl +Scripts page which shares the same constraints as these Bash +Scripts do.
+

+ Direct Cognition: +View the scripts directory itself rather than navigating with the links +below: scripts. +
    +
+
+
+

 

+
+ + + + + + +
+

Assorted Bash Script Files

+
+

uhh.sh

+
This documentation page isn't quite ready yet.
+In fact, this file is still in its very first few iterations and is +pretty +limited so far...
+
+

cvs_importer.sh

+
This script eliminates the need to use the cvs +import command to pull in a whole new sub-hierarchy.  Given a +sub-folder under an existing hierarchy, it will add all the +subdirectories and all of the files in those subdirectories.  The +script avoids adding any files found in the internally used CVS +directories.
+For example, suppose you have a folder called "hoople" that's a +top-level project in CVS.  You want to add a new folder under the +existing hierarchy "hoople/source/lib_src" called "pasta".  The +"pasta" hierarchy has hundreds of subdirectories and thousands of +files.  Assuming that you've already moved the new pasta source +folder into place, the command would be:
+    cvs_importer hoople/source/pasta
+If you don't have the Yeti aliases set up, then you may need to type +this instead:
+    bash ~/yeti/scripts/cvs_importer.sh +hoople/source/pasta
+
+

+

movie_seeker.sh +/ movie_stripper.sh +/ show_stripper.sh
+

+
Some manipulation methods for a +particular type of movie and TV show database.  These expect a db +in the form of a CSV file with three fields per line: (1) index number, +(2) show or movie name and (3) show episode title.  The third +field is defined as blank for movies.  The movie_seeker finds a +given movie (or pattern) in the database.  The movie_stripper +pulls out all the unique movie or show names in the database.  The +show_stripper pulls out the episode names for a particular show name +(or pattern).
+
+

call_movie_seeker.sh +/ call_movie_stripper.sh +/ call_show_stripper.sh
+

+
These are CGI correspondents to +the above movie database searches.  They're used on the Gruntose +web site.
+
+
+
+
+
+
+
+
+
+ + diff --git a/doc/binaries_note.txt b/doc/binaries_note.txt new file mode 100644 index 00000000..e4191f65 --- /dev/null +++ b/doc/binaries_note.txt @@ -0,0 +1,22 @@ + +There are a few pre-built binaries included with hoople. +They originate from a few different sources. Feel free to not trust them. + +These apps are external to the HOOPLE build... + +build/msys hierarchy: + This is copied directly from the msys project of MingW. + It has had zip.exe, unzip.exe and short_path.exe added to it. + + unzip.exe & zip.exe: + The zip and unzip tools are from the info-zip project. They are somewhat + antiquated but still work great on the various 32-bit windows platforms. + These utilities are self-identified as: "Zip 2.3 (November 29th 1999)" + To get a more recent version of the zip utilities or build them yourself, + they can be found at the site: http://www.info-zip.org/ + + short_path.exe: + Built by the hoople bootstrapping process, but unfortunately this tool + is desperately needed for windows builds to work nicely with clam and + bash. It can be replaced by any newer working version from the bootstrap. + diff --git a/doc/clam_manual/clam_docs.html b/doc/clam_manual/clam_docs.html new file mode 100644 index 00000000..2d2ec39a --- /dev/null +++ b/doc/clam_manual/clam_docs.html @@ -0,0 +1,2334 @@ + + + + + + + CLAM Reference Manual + + +
+ +

CLAM: Coordinated Librarian &

+

Automatic Maker

+
+
+
+ +

Tutorial and Reference Manual

+
+
+ +
By Chris Koeritz (koeritz@gruntose.com)
+
+
+ +

+

+
+
+ +

Table of Contents

+
+
    + +
  1. Executive Summary
    2. + +
  2. Preparing Your Computer to Use +CLAM
    3. + +
      + +
    1. Necessary Steps
      2. + +
    + +
  3. CLAM Tutorial
    4. + +
      + +
    1. Caveats
      2. + +
    2. Basics
      3. + +
    3. Common Files
      4. + +
    4. Important Variables
      5. + +
    5. Variable Assignment
      6. + +
    6. Optional Variables
      7. + +
    7. Writing Your Own Rules
      8. + +
    8. Conclusion
      9. + +
    + +
  4. CLAM Reference
    5. + +
      + +
    1. Language Independent +Variables
      2. + +
    2. Language Independent +Rules
      3. + +
    3. Language Independent +Targets
      4. + +
    4. Language Independent +Files
      5. + +
    5. C++ Specific Variables
      6. + +
        + +
      1. Directory Structure +Variables
        2. + +
      2. Compiler Dependent Flags
        3. + +
      3. Microsoft Visual C++ Only
        +
        4. + +
      4. Support for +Compilation +Extensions
        5. + +
      + +
    6. C++ Specific Rules
      7. + +
    7. C++ Specific Targets
      8. + +
    8. C++ Specific Files
      9. + +
    + +
  5. Example CLAM Makefiles
    6. + +
  6. CLAM Hints and Troubleshooting
    7. + +
  7. Acknowledgements
    8. + +
+
+ +

+

+
+
+ +

Executive Summary

+
+    The CLAM system is a set of macros and rules +for the GNU make program +that +simplifies the creation of executable programs and code +libraries.  +Most makefiles that use the CLAM system are ten lines long or +less.  +Makefiles are stated in terms of a set of special variable names that +CLAM +interprets in order to issue the correct sequence of compilation +directives.  +This document presents a tutorial on the variable names and simple +rules +that need to be used with CLAM.  Several example makefiles and the +full +reference manual for CLAM are also included.
+    CLAM is part of the HOOPLE libraries (http://hoople.org/) and can be +downloaded from there or through a sourceforge mirror site.
+    In the remainder of the document, we will often +refer to CLAM as just "clam".
+  + +
+

+

+
+
+ +

Preparing Your Computer to Use +CLAM

+
+

Necessary Steps:

+
    + +
  1. Setting environment variables for clam:
    2. + +
      +
    1. FEISTY_MEOW_DIR:
      2. + +
        + +
      1. +**REVISE** out of date... + +This variable has been needed since clam became +part of the YETIcode project (at http://yeticode.org).
        2. + +
      2. The default location for clam is under the FEISTY_MEOW_DIR +in a +folder named clam, although the version of clam shipped with the HOOPLE +code (http://hoople.org) actually lives under the root of the hoople +hierarchy.
        +
        3. + +
      3. If the yeti root directory is in $HOME/yeti +already, then the +default for FEISTY_MEOW_DIR will work and it doesn't need to be declared.
        4. +
      4. Setting the variable:
        +
        5. + +
          + +
        1. On Unix (with the bash shell): export MAKEFLAGS="-I $HOME/yeti/clam"
          2. + +
        2. On win32: set +MAKEFLAGS="-I c:/yeti/clam"  (or set this in the System +control panel, under the advanced tab, in environment variables)
          +
          3. + +
        3. Note that the use of +forward slashes is mandatory in the clam directory in MAKEFLAGS.
          +
          4. + +
        + +
      + +
    2. MAKEFLAGS:
      3. + +
        + +
      1. This variable is required to be set in the +environment before using clam with gnu-make.  It tells make where +to find the clam definitions and scripts.
        2. + +
      2. Setting the variable:
        +
        3. + +
          + +
        1. On Unix (assuming bash as shell): export MAKEFLAGS="-I $FEISTY_MEOW_DIR/clam"
          2. + +
        2. On win32: set +MAKEFLAGS="-I %FEISTY_MEOW_DIR%/clam"
          3. + +
        3. This variable also requires forward slashes +instead of +backslashes.
          4. + +
        + +
      + +
    + +
  2. Required Tools:
    3. + +
      + +
    1. The compiler itself:
      +
      2. + +
        + +
      1. If you are running GNU/Linux (or almost any other +Posix-compliant operating system), then the GNU C/C++ compiler +suite is pretty much all that's needed.
        2. + +
      2. The +GNU C/C++ compiler (included in the MinGW +toolkit) should be all that's needed for +compilation, +but the Microsoft Visual Studio 6.0-8.0 compilers can be used if +available.  Compatibility is only guaranteed for vc8 +however.
        +
        3. + +
      + +
    2. Win32 Unix Tools:
      3. + +
        + +
      1.  If you are running a win32-based product +(windows NT, +windows +2000, +windows xp, etc) then a few additional tools are required...
        +
        2. + +
      2. The recommended GNU utilities are available for +win32 in the +MingW MSYS +package (http://www.mingw.org/).
        3. +
      3. The MSYS tools are actually included in the source safe +archive for +hoople. The version provided by hoople is recommended +because a +couple of missing tools have been added back in.
        4. +
      4. They can also be downloaded the mingw web site: MSYS +package: msys_bins.tar.gz
        5. +
      5. Note that you will need to add the +binaries +directory from MSYS +to +your path.  The PATH variable can be accessed under MS-NT type +OSes through the +"control panel | system | advanced | environment variables" menu +trail.  If you plan to use msys outside of clam, then ensure that +the MSYS bin (l:/msys/bin) directory is prior +to the +windows system directory in your path; this causes the Unix "find" +command to be used instead of the NT version.
        6. +
      6. Alternatively, a similar set of GNU utilities is +available +in the Cygwin +package, although these tools are no longer recommended and are, in +fact, actively deprecated.
        7. + +
          + +
        + +
      + +
    3. makedep and version_stamper tools:
      4. + +
        + +
      1. The hoople/bin directory in the archive has +pre-built +versions of tools used by clam during a build.
        +
        2. + +
      2. If you would rather rebuild them from source, then +running +the script "bin/bootstrap_build.sh" will +recreate all of these internal tools.
        +
        3. + +
      + +
    + +
  3. Third Party Tools Used By or Supported Within clam:
    4. + +
      + +
    1. wx widgets:
      2. + +
        + +
      1. home page: http://www.wxwidgets.org/
        2. + +
      2. As far as the clam team is concerned, this is the +premier +portable (and open source) library for graphical user interfaces.
        +
        3. + +
      + +
    2. OpenSSL:
      3. + +
        + +
      1. home page: http://www.openssl.org/
        2. + +
      2. This is the team's most favorite library for SSL +(Secure +Sockets Layer) and general encryption needs.
        +
        3. + +
      + +
    3. cURL:
      4. + +
        + +
      1. home page: http://curl.haxx.se/
        2. + +
      2. The curl library rocks(!) and provides a very +powerful set of +tools for programmatically interacting with live web pages.
        +
        3. + +
      + +
    + +
  4. Other clam Preconditions:
    5. + +
      + +
    1. Linux platforms:
      2. + +
        + +
      1. The standard source code repository is a directory +called +"hoople" +in the user's home directory.  If you decompress the hoople +library archive in your home directory, you should be all set to +perform a build.
        2. + +
      2. See the HOOPLE website for more details about +downloading that codebase (http://hoople.org).
        +
        3. + +
          + +
        + +
      + +
    2. Win32 platforms:
      3. + +
        + +
      1. The standard repository for source code is a substituted drive l:, which is where all the other hierarchies start.  This +drive can be mapped to any folder desired using the "subst" command +(for example, "subst l: c:\build_dir"). + All +objects and final products will be generated to the l: drive.
        2. + +
      2. Using MS Visual Studio as the Compiler:
        3. + +
          + +
        1. VS80COMNTOOLS/VS90COMNTOOLS/VS100COMNTOOLS variable:
          2. + +
            + +
          1. This variable should be automatically created by +Visual Studio upon installation.  If it isn't, then Microsoft has +a bug or you need to restart your current prompt or your computer.
            +
            2. +
          2. The paths that clam uses to find compiler binaries +is calculated based on this variable.
            3. +
          3. Older versions of visual studio are currently +unsupported because Microsoft constantly rearranges their folders and +tools in a non-maintainable way.
            +
            4. +
          +
        2. Several other environment variables are required +by Visual +Studio.  They can be set up for your current command prompt by +running "vcvars32.bat" or "vsvars32.bat" (found under +the +compiler's common directory, which varies depending on the version of +visual studio).
          +
          3. + +
        + +
      + +
    + +
+
+ +

+

+
+
+ +

CLAM Tutorial

+
+     This section provides an overview of +how clam +works and how you can make it work for you.  It is quite brief, +but +should suffice for most common cases of makefiles.  For more +detailed +usage, consult the CLAM Reference section of this document. + +

Caveats

+ +

+Basics

+     The C++ Library +Automatic Maker system (or CLAM) is defined as a set of +variable +(or macro) definitions.  These variable definitions are +manipulated in +order to compile and link programs.  By setting the variables' +values +appropriately, specific products can be generated from the target rules +defined +in clam.  Both variables and rules are extensible.  The +general +procedure for building a clam-based Makefile has four user-defined +steps: + +
    + +
  1. loading the default variables for clam,
    2. + +
  2. redefining the default variables where necessary,
    3. + +
  3. loading the default rule set for clam,
    4. + +
  4. defining rules that are local to the user's Makefile.
    5. + +
+Step 4 can usually be omitted unless the project creates +components +whose types are not supported by clam.
+     clam is structured as a directory hierarchy +where the root of clam +supports +the most general makefile activities.  Activities such as +recursing +into subdirectories and providing support for cleaning up after a make +are +provided at this level.   In the remainder of the document, we +will +designate this location with a "$" character to clarify what part of +the clam hierarchy we are describing.
+     The root clam +support files are mostly language independent, since they are used by +all +varieties of language dependent derived versions of clam.  These +files +are generally not of concern unless one is designing a new derived +version +of clam for a language not yet supported.
+     The subdirectories off of the clam root +provide +"derived" makefile services, such as C++ or Ada compilation.  Each +derived clam service implements at least two files to link into the +rest of the +clam system: a variables file and a rules file.  The variables +file defines +the options for the derived make process; by changing the values of +these, +different types of targets can be created.  The rules file +implements +creation of the targets relevant to the programming language being +supported.
+     It may be worth noting that clam can be used to +drive +any kind of programmatic process--not just compilation.  Currently +though, +program compilation is the primary goal. + +

Common Files

+     The top-level file called +"$/variables.def" +contains +definitions and descriptions of the variables used throughout the clam +system.  For a non-derived type of make (using only base clam +support), +this file should be included near the start of the user's +Makefile.  +The rules file (stored in "$/rules.def") should be included after the +user +has modified the appropriate variables that will dictate how the make +is +performed. +
+     This scheme of including variables at the +top and then rules at the bottom of the user's makefile is employed in +all clam makefiles.  For example, makefiles for C++ compilation +are structured the +same way.  The user's C++ makefile includes the C++ variables +(stored +in a subdirectory called "$/cpp" under the clam root) at the top of the +makefile and then includes the C++ rules at the bottom.
+     An example +of a C++ makefile is shown below: + + +The interior of the makefile overrides the TYPE, SOURCE +and TARGETS variables for C++ compilation to specify what is to be +built +(basis.lib) and what it consists of (the CPP files mentioned in +SOURCE).  + The PROJECT variable being overridden is actually defined in the +$/variables.def; +a project name is a required feature of all clam makefiles. + +

Important Variables

+     +The clam root directory is pointed to by an internal variable called +"CLAM_DIR", +defined in $/variables.def.  This variable is used by the clam +system +to find extra files that might be needed by derived makefile +support.  +It is important to change this to the appropriate value when you are +using the system in a different location.  The CLAM_DIR variable +can either +be directly edited in $/variables.def, or it can be overridden in the +environment +of the shell running the make, or it can be passed on the command line +to +make.
+     For C++ compilation, the above example +makefile +(for basis.lib) contains examples for most of the required +elements.  Additional elements +will be discussed in the examples section or can be found in the +reference.  +The absolutely required variables for C++ are PROJECT, TYPE, SOURCE and +TARGETS. + +

     PROJECT is a variable that +provides the +name +of the project being compiled.  This should be a word that can +also +be used as a directory name and partial component of filenames.  +Thus, +spaces and other unusual punctuation characters are discouraged.  +All of the project's temporary directories will be created based on +this +variable.  This project name should be unique across a full build; +otherwise files generated by compiling identical project names will be +jumbled together. +

+

     TYPE is a variable that describes +the kind +of project that is being compiled.  This is necessary because it +controls +some aspects of the compilation, such as where the compilation products +are +generated.  All files generated by compilation are stored in the +repository +directory (by default, either "~/hoople" in Linux or "l:\" in +win32).  There are three TYPEs supported so far:

+ +     Projects of the "library" type will +be given +an include directory named after the project, such as +"~/hoople/include/basis". + The include directory is created as a copy of the headers in the +project's +directory .  Library projects will also have their final products +copied +to the lib or dll subdirectories of the build directory being created.
+     Projects that are of type "application" will +have their executables +copied to the executable directory in the repository (such as +"~/hoople/exe").
+     The "test" type of project +will be promoted to a subdirectory named after the PROJECT that resides +under the test hierarchy in the repository (such as +"~/hoople/tests/turbodog"). + +

     SOURCE is a list of files that +are to be +compiled +in order to create the final products of the project.  These can +be +C++ source files (*.cpp), MS-Win32 resource files (*.rc) and other +types +of source files.  The list of objects to create will be determined +by transforming the list of SOURCE files (such as by turning a file +called +"fud.cpp" into an object called "fud.obj"). +

+

     TARGETS is a list of the products +that are +to be created by compilation and linking.  The suffix of a target +is a well established extension, such as ".lib", ".exe" +or ".dll" for MS-Win32 compilation products. +

+

Variable Assignment Policies

+     +The assignment of variable values is mostly straightforward, but it +might +be valuable to provide a refresher.  In GNU make, a variable +(a.k.a. +macro) can be assigned using the following syntax: + + +This sets the variable named FRED to the value of "a +b c".  The variable is referred to as $(FRED) when it is being +used, +although its name is just FRED.
+     This syntax is fine when the variable is to be +defined only once.  +In many cases though, a variable is already defined and needs to be +added +to instead of redefined.  Using the standard equals (=) operator +would +wipe out the previous definition, so a special assignment +is provided: + + +This is quite similar to the C syntax on integers.  It +means that +FRED will be given a value equal to its old value plus the new +contents.  +In our example, FRED would be equal to "a b c d e f".  Note that +one cannot say:
+
+          FRED = $(FRED) d e f +      (BAD!)
+
+This is not allowed in GNU make because it includes a macro's own value +in its definition.  This causes a badly formed recursive +definition +of the variable; a variable dereferencing operation (such +as $(FRED)) causes the variable's current value to +be resolved, which in turn dereferences any other variables in the +definition. + Thus, the reference to $(FRED) causes infinite recursion when +included +in the definition of FRED.
+
+     In the case of variables that must +be defined by the user's makefile, the standard assignment operator +(via the = character) can +be used.  This includes the PROJECT, TYPE, SOURCE, and TARGETS +variables.  +Also, any other variables that are set only by the user's makefile can +use simple assignment.  This category includes LOCAL_LIBS_USED, +LIBS_USED and others of similar nature.
+     But several variables are defined partially +by clam, then added to within the user's makefile, and then possibly +extended +after the user's makefile is processed (by the clam rules file).  +These variables cannot use +standard assignment and must instead use the incremental assignment +(+=) +operator.  Variables included in this category are DEFINITIONS, +LOAD_FLAG_PREFIX, +CLEANUPS, and many others. +
+     If you are unsure about the type of variable +you are defining, then the incremental assignment (+=) operator is +preferred +to avoid trashing the variable's previous values.
+     +Note that when variables are "exported", then any make in a subshell +will +inherit the parent shell's value.  This can induce some weird +behavior +for variables that are incrementally constructed with the += +operator.  +If this seems to be happening, try using the simple assignment operator +for +that variable in the sub-makefile, if this is allowed.  In general +though, +variables are not exported unless they MUST be seen by shell scripts +and +this does not occur overly frequently. + +

Optional Variables

+     There are several miscellaneous +variables that +are useful, either within one's makefiles or when passed to GNU make on +the command +line.  These are described below. + +

     LOCAL_LIBS_USED is a list of +library names +that are to be linked in with the library or executable being +created.  +These are specially formatted names; they are just the prefix part of +the +full library name.  For example, if you're building a release +executable +and want to link in a data structures library "i_adt.lib" (win32) or +"libi_adt.a" (Linux), you can specify: +
+        LOCAL_LIBS_USED = i_adt +
+The appropriate prefix and suffix will be attached. +

+

     EXTRA_COPIES is a list of files +that should be copied to a project's output folder when it is done +being compiled.  These should be files that are not already +copied as the main products, such as extra data or configuration files +that belong with an application. +

+

     EXTRA_VERSIONS is a list of +version files +that +also need to be updated to the main build version during a +compilation.  +These are usually needed if a project compiles several executable +files, +and each one performs version checking.  (By default, any project +containing a file called "version.ini" will get a version stamp from +the +main build version.) +

+

Writing Your Own Rules

+     One might need to write new rules +for +processing +file types that are not directly supported by clam.  There are a +number +of features provided for writing rules, but there are also some +requirements +placed on the rules. +
+     All rules in makefiles need to be prefaced +with one of the provided "launcher" macros.  These are used to +ensure +that the rules can be properly executed on different platforms; +Windoze95 +was especially hard to implement for until these macros were developed +(due to what appear to be basic defects in the command line +support).  +All preaching aside, here are the macros: + + +Here are some examples of using the macros properly.  +Note that +the +command itself must be contained in single quotes:
+
+$(HIDER) $(MIDL) crumpet_server.idl
+ +
MIDL is also a provided macro; it executes the +Microsoft +IDL compiler.
+$(HIDESH) $(CLAM_DIR)/postconditions.sh
+ +
This runs a shell script that handles the end +portion of a +make.
+

+Conclusion

+     This tutorial is intended to raise +awareness +of +basic  usage.  Hopefully the reader will now be able to +create +simple makefiles that use .  For more aggressive compilation +requirements, +the reference section may be needed; it describes every variable and +rule +used in the  system.  However, it is most likely the case +that +your unsupported compilation needs will also be required by others in +the +future, and it is hoped that you will contribute them to the +main-line  support.  Currently, the appropriate way to do +this is just +to +send the makefile code to the library +administrator, who will include them +in the next version of . + +
+

+

+
+
+ +

CLAM Reference

+
+

+Language Independent Variables

+     The language independent variables +are stored +in the file "$/variables.def".  They define the overall structure +of a make and can usually be overridden to customize how the make is +performed. + +

BUILD_BEFORE

+     This is a list of projects that need +to be +created +before this project can be created.  The items in the list are +interpreted +as directories that contain a makefile to be run.  For example, if +an item in BUILD_BEFORE is listed as ‘fred’, then the target +"fred.make" +will be executed.  That target changes to the directory 'fred' +before +running the makefile there.  The project in the specified +directory +is created using make if needed (as determined by that directory's +Makefile).  +The projects in BUILD_BEFORE are made immediately after the +FIRST_TARGETS +are made. + +

ACTUAL_TARGETS, ACTUAL_FIRST_TARGETS, ACTUAL_LAST_TARGETS

+     See below for TARGETS, FIRST_TARGETS and +LAST_TARGETS.
+ +

BUILD_AFTER

+     A list of directory names that +should be +recursed +into after this project finishes.  Each listed directory will have +make +started on any makefile found.
+ +

BUILD_BEFORE
+

+     A list of directory names that +should be +recursed into before this project +starts.  Each directory listed will have make started on any +makefile found.
+ +

MAKEFILE_NAME

+     A variable that specifies the name +of the +makefile +for all sub-makes.  It works with BUILD_BEFORE and +BUILD_AFTER and allows the name of the makefile in a +subdirectory to be changed to something other than 'makefile'.  +This +supports different types of builds which are controlled by different +makefile +names. + +

PARAMETER_FILE

+     A file name that is +usually found at the root of the repository.  The name is +often "build.ini", but any name can be used as the parameter file. + This file is an extension of the variable set included in +$/variables.def +and can be used to provide compilation paramters without resorting to +the +command line.  This file is associated with a particular build +rather +than the  support, so different releases will have different build +parameter +files.  On systems supporting version information, the build's +version +number is stored here also.
+ +

CATCHER

+     A sub-program launcher like HIDESH +but this will trap errors it sees and play the build error +CLAM_ERROR_SOUND.
+ +

CLAM_BIN

+     This is a folder where the helper +binaries for  are located. The default for this is usually +CLAM_DIR/../bin.
+ +

CLAM_DIR

+     This variable points at the location +where the  definitions and helper scripts are located.  The +default is +"~/yeti/clam", +but this can be overridden for local installations of .
+ +

CLAM_ERROR_SOUND

+     This is a list of sound files +that should be played when a make stops with an error.  It serves +as +an audible warning that something bad happened.
+ +

CLAM_FINISH_SOUND

+     This is a list of sound files +that should be played when the make has concluded +successfully.  It should play when the outer-most make +has seen all targets created as intended.
+ +

CLAM_TMP

+     Specifies the location for temporary +files generated during a make.  The default value usually works +fine. + This directory will be created if it does not already exist.
+ +

CLEANUPS

+     This is a list of files to be +removed by the +make +clean command.  They are possibly acquired from the TARGETS +defined +in the user's Makefile, or by language dependent rules for +cleaning.  +Additional files can be added to this list by the user's makefile also. + +

DIRTY_FILE

+     This variable points at a file that +signifies +that some targets have been remade.  It is not used at the base +level +of clam, but language-specific versions might do something special if +targets +were remade (such as put them in a build repository). + +

FAILURE_FILE

+     This file is used as a flag that +indicates +when +a make has failed.  The particular file used depends on the +project +name for this makefile.  It is cleared at both the beginning and +end +of a make. + +

FIRST_TARGETS

+     The FIRST_TARGETS are made before +any +libraries +are created and before any executables are compiled.  There must +be +a rule for making every entry in this list, either through implicit +rules +or explicit ones provided by the user's makefile. + +

FLAG_FILES

+     This is a list of all the files +that are used for compilation flags.  They are whacked at the +beginning +and end of a make.
+ +

HIDER

+     This macro is used throughout  +to hide the +commands that are being sent to the operating system.  It can be +disabled to allow a verbose make (see the NOISY macro). + +

HIDESH

+     Just like HIDER, but this macro is +specifically +for launching shell scripts.  Some versions of GNU make (like +Cygwin's) +have problems running scripts which don't arise when running executable +files. + Those problems led to the creation of the HIDESH macro for those +specific +cases.  This is not an issue for Unix systems. + +

 LAST_TARGETS

+     The LAST_TARGETS are made after all +of the +other +standard targets are made.  Their must be a rule for making every +entry in this list, either through implicit rules or explicit ones +provided +by the user's makefile. + +

NOISY

+     This variable can be used to cause a +verbose +make.  +If the variable is non-empty, then all commands will be echoed to +standard +output.  Otherwise, the default is to hide the commands that are +issued +and just show the output of running those commands. + +

OP_SYSTEM

+     This is a flag that defines the +operating +system +name.  This flag is sometimes used to choose the appropriate tools +per platform or to conditionally compile code for system +dependent interfaces.  The available possibilities so far are +UNIX, +OS2, SYSV (System V Unix), DOS, and WIN32.  Only UNIX and WIN32 +are +currently very functional. + +

 OTHER_CLEANS

+     These are targets to execute before +performing +the main clean up during "make clean".  These might be targets +that +contain shell commands to execute as part of clean up or they could +contain +the "clean_subdirs" command (defined below). + +

PROJECT

+     This is a variable that provides the +name of +the +project being compiled.  This should be a word that can also be +used +as a directory name and as a partial component of filenames.  +Thus, spaces +and other unusual punctuation characters are discouraged.  All of +the project's temporary directories will be created based on this +variable. + +

FEISTY_MEOW_DIR

+     Specifies the root directory +for compilation or other  building activities.   The +repository +is also where source code and final products of compilation reside, +unless +the default is over-ridden (see TARGETS_DIR).
+ +

SH & SHELL

+     These variables both point at a +shell program +that is +used for starting commands.  SHELL is defined by GNU make, whereas +SH is defined by . + +

SUB_FLAG_FILES

+     This is a list of the compilation +flag files +which +should be destroyed only at the end of a make.  They are used for +communication +with submakefiles--makefiles that were invoked by "this" makefile.
+ +

SUBMAKE_FLAG

+     This points to a file whose presence +indicates +that +a "submake" performed some actions.  The flag can be interpreted +by +some language-specific versions of  as a reason to set a flag +using +the +DIRTY_FILE.
+ +

TARGETS

+     These are the products to be created +by .  +Each item listed in TARGETS should have a rule that knows how to create +that type of file.  The language independent system provides very +few suffix based rules.  TARGETS is filled in by the user in +their  file, but it is not used directly by the  +system.  +Instead, +a generated variable called ACTUAL_TARGETS is used.
+ +

TARGETS_DIR

+     This folder is where all generated +files are +to +be stored.  It is usually identical to FEISTY_MEOW_DIR but can be +overridden +when the targets should be stored elsewhere.
+ +

Version components: major, minor, revision, build
+

+     These four variables specify the +version of +this +particular build.  They are usually stored in the +PARAMETER_FILE. + The major and minor versions are the traditional 2.3, 4.0, etc +style +of release numbers.  The revision number is often used to sequence +the +builds of that particular release, such that build 3.5.127 is the 127th +build +of the 3.5 release.
+     A version-tagged file (such as an executable or +dynamic +library) with any one of the major, minor or revision numbers differing +from +an installed build is incompatible with the installed build.  An +executable +file or dynamic library will not be allowed to load other dynamic +libraries +where these numbers differ.
+     The last version component is misleadingly called +"build"; +this number specifies the service pack level for a file.  Files +whose +versions only differ in the last "build" component are intended to be +compatible +with each other.  The understanding is that if only that number +differs, +then the external interface to the file has not changed, although the +interior +implementation may have.
+ +

Language Independent +Rules

+     The file "$/rules.def" uses the +composite +macros +defined in "$/variables.def" together with a set of make rules to +perform +actions during compilation.  The rules file should be included in +the user's Makefile after the compilation variables have been +initialized +for the project being compiled.  The user's own targets should be +placed after the directive that includes "$/rules.def". + +

%.halt

+     These targets cause  to exit, +usually to +avoid +something that it considers catastrophic.  An example of this +would +be when  finds an inappropriate entry in the list of objects to +create; +allowing a "make clean" on this makefile will delete files that are +probably +not intended.  Hence, when  finds this kind of usage, it will +stop the make and issue a complaint. + +

%.make

+     Used to compile a makefile in a +subdirectory +named +"%".  This rule is employed by the BUILD_BEFORE macro, but can be +used in the user's makefile targets also. + +

Language Independent +Targets

+    The following targets are defined by +"$/rules.def". + +

all

+     This is a standard target that is +executed +when +no particular target is specified at the make command line.  It is +an umbrella target that invokes all of the other targets required to +perform +a make.  The order in which the major targets are created is: + +
    + +
  1. FIRST_TARGETS
    2. + +
  2. TARGETS
    3. + +
  3. LAST_TARGETS
    4. + +
+

+clean

+     This causes all of the files in +CLEANUPS to be +removed and also executes all of the targets in OTHER_CLEANS.  The +language dependent system can override some of this behavior or it can +just add more files to the list of CLEANUPS. + +

clean_subdirs

+     This is similar to "make_subdirs" in +that it +descends +into the subdirectories in no particular order, but it runs "make +clean" +in each of them.  This allows a directory hierarchy of projects to +be cleaned with one command. + +

finish

+     The "finish" target represents the +completion +of a make, whether successful or not.  It reports the time and +date +(and logs them). + +

rm_links

+     This target causes all link files in +the +current +directory to be deleted.  This is only applicable on a Unix +operating +system. + +

make_subdirs

+     This target allows a makefile to +specify that +all of the subdirectories under the current directory should be scanned +for makefiles and that those makefiles should be executed.  If a +makefile +does not exist, it is skipped.  Note that the subdirectories are +descended +into in no particular order; the order depends on how the operating +system +decides to list the directories.  If the order of make is +important, +use BUILD_BEFORE instead. + +

start

+     The "start" target represents the +beginning of +the make.  It reports the time and date (and logs them). + +

Language Independent +Files

+

$(PARAMETER_FILE)

+     This is a special +file that has at least two purposes in .  It is the source of +the +version number that will be stamped on all the appropriate DLLs and +EXEs +created during a build.  It is also a place where build-wide +compilation +directives can be included so that they do not have to be passed on the +command +line.  For C++ compilation, this is usually an INI file +stored in the +FEISTY_MEOW_DIR under the build folder.  +Here is a sample parameter file: + +
#\
+ [version]
+ major=14
+ minor=3
+ revision=140
+ build=0 +

DEBUG=t
+ OPTIMIZE=t
+

+
+Note the bizarre comment at the top of the makefile; this is +used to +hide +the "[version]" section marker.  The comment is required because +the +build parameter file is pulled directly into the makefile code to set +the +variables after the version stamp.  Without a comment in front of +the section, a syntax error would result.  The "[version]" section +marker is required because this file is also sometimes treated as a +win32 INI file +in order to read the version stamp.
+     The build version is stored in the first four +entries.  Our interpretation of the stamp is standard for "major" +and "minor".  We treat the "revision" as a build revision number; +within a release, there will be numerous revisions--one for each new +build +that is performed.  We then treat the "build" entry as a patch +level +within that particular build.  When we perform our version +checking, +only the first three entries are compared; the patch level in "build" +is +considered irrelevant. +
+     This example also specifies that the build +should be a debug style (rather than release) build and that it should +be optimizer.  We can also see that +the flags for bounds checker instrumentation and true time +analysis support are commented out.
+ +

badness_catcher.sh

+     Runs the command line passed +in as a sub-shell and looks for error conditions.  If an error +occurred, +the build is stopped and the CLAM_ERROR_SOUND is played.
+ +

datestamp.sh

+     Echoes the time and date.  This +is a +separate +file to make the cross-platform difference less annoying.
+ +

exit_make.sh

+     Causes the make to stop dead in its +tracks. + +

postconditions.sh

+     Invoked at the end of the +language-invariant +portion of a make.
+ +

preconditions.sh

+     Invoked at the beginning of the +language-invariant portion of a make.
+ + +

starter.sh

+     This shell script executes a command +that is +passed +to it as its parameters and logs error conditions to standard +output.  +It's used by the CATCHER macro. + + +

+

+

+C++ Specific Variables

+     These variables are used throughout +the C++ +compilation +support.  They are defined in "$/cpp/variables.def". + + +

BASE_CPU

+     Allows specification of the +processor that the +build is targeted for.  This is needed when special actions must +be +taken for different processor types.  Valid values currently +include +m68k (for Motorola 68000 series), m68340 (specifically the 68340), +x86 (intel 386 and upwards), and ppc860 (the PowerPC 860). + +

BUILD_LIST_FILE

+     The list of files that must +be rebuilt.  This is only used with compilers that support +compilation +of multiple source files with one invocation of the compiler (currently +only +MS-Visual C++).
+ +

BUILD_WHACK_FILE

+     A list of object files that must be +destroyed +if +the make fails.  This is only relevant in the same situations as +BUILD_LIST_FILE.
+ +

COMPILER

+     This variable chooses the specific +flags +needed +for the compiler.  Not all operating system choices above are +suitable +with the COMPILER choices, but generally it is fairly obvious which are +supported.  The current possibilities include BORLAND_DOS, +BORLAND_OS2, +UNIX (default cc), GNU_OS2, GNU_LINUX, OBJECT_CENTER (Saber compiler), +SUN_UNIX, +VISUAL_CPP, and DIAB3. + +

COMPILER_FLAGS

+     This is the list of flags passed to +the +preprocessor +and compiler. It is composed of the SYSTEM, the DEFINITIONS, the +SEARCH_DIRS, +and any user-included options. If flags that don't fit one of the +categories +are needed, they can be added here. + +

CONSOLE_MODE

+     This causes the program +to be generated as a console application.  This is relevant in +systems +(such as win32) where programs have a split personality depending on +whether +they are to have graphical user interfaces or just console interfaces. + +

DEBUG_FLAGS

+     These are flags used for generating +specialized +versions of object files, such as ones that include debugging code +(e.g., +for gdb) or ones that add code for profiling (e.g., gprof). Possible +values +in the Sun CenterLine Compiler environment are -g for debugging code +and +-pg for profiling. + +

DEFINITIONS

+     This is a list of compiler flags +that define +the +value of C or C++ macros. These usually have the format of +‘-D<flag>’, +but in this particular variable only the <flag> itself should be +listed +(because the compiler option characters ‘-D’ are added automatically). + +

DEPENDENCY_ADDITIONS

+     This is a list of extra flags that +gets passed +to the auto-dependency tool.  The list can vary for each compiler. + +

DEPS_FILE

+     This file is where the +auto-dependency +information +is stored.  The "makedep" program is used to generate +auto-dependency +information for the files listed in SOURCE.  During a build, the +DEPS_FILE +is pulled into the actual code of the makefile; this causes the +dependencies +to be automatically included so that they can dictate the files that +need +to be rebuilt. + + +

EXTRA_VERSIONS

+     This is a list of version files that +also need +to be updated to the main build version during a compilation.  +These +are usually needed if a project compiles several executable files, and +each one performs version checking.  By default, any project +containing +a file called "version.ini" will get a version stamp from the main +build +version. + +

LIBRARIAN_FLAGS

+     This is a list of flags that are +passed to the +library creation tool.  Sometimes this must be overridden for a +particular +compiler. + +

LIBS_USED

+     These are code libraries that the +executables +depend upon.  They are searched for in any of the directories +listed +in the LIBRARY_SEARCH_PATH. + +

LOAD_FLAG_PREFIX & LOAD_FLAG_SUFFIX

+     These tell the linker and loader how +to deal +with +the files and where to locate library components. The prefix is listed +on the compilation command line before the object files are listed, and +the suffix after. The prefix should contain information such as the +directories +to be searched for code libraries (although they should be added to +LIBRARY_SEARCH_PATH).  +In the suffix definition, actual library loading statements (like +-lmath) +can be included (although they should be listed in a different form in +LIBS_USED or LOCAL_LIBS_USED). + +

LOCAL_LIBS_USED

+     The names in this list actually +cause the +OBJECTS +to be recompiled when the libraries listed have changed.  To +accomplish +this, these libraries MUST be located in the STATIC_LIBRARY_DIR rather +than +at some arbitrary place on the LIBRARY_SEARCH_PATH.  These +libraries +also must follow the special naming convention followed by ; if +"basis" +is an entry in this list, then a library called "basis.lib" will be +sought +during the build. + +

NO_COMPILE

+     Specifies that no compilation +should be performed.  Nothing in the SOURCE or TARGETS macros will +be +built.
+ +

NO_DEPS

+     This is an exclusion flag.  If +it is +defined, +then no auto-dependency files will be generated.  This is useful +if +you're missing the makedep tool and trying to compile it.
+ +

OBJECTS

+     The OBJECTS are all those files that +need to +be +created during compilation.  Usually this list is filled based on +the files in SOURCE. + +

OPTIMIZE

+     Causes the make to create optimized +code.  +The default optimization is for speed. + +

REBUILD

+     If the REBUILD variable is +non-empty, then all +files listed in the SOURCE variable are touched.  This should +cause +all of those files to be rebuilt during the compilation.  +Occasionally +GNU make will complain that a file is newer than the current time, but +this does not usually cause any problems. + +

SOURCE

+     The SOURCE variable is a list of +files that +are +to be compiled in order to create the final products of the +project.  +These can be C++ source files (*.cpp), Win32 resource files (*.rc) +and +other types of source files.  The list of objects to create will +be +determined by transforming the list of SOURCE files (such as by turning +a file called "fud.cpp" into an object called "fud.obj").  More +file +types will be added as they are needed. + +

STATIC

+     Causes the make to create statically +linked +targets.  +Executables or dynamic libraries will not link in any compiler supplied +dynamic libraries, nor will they require them during run-time. + +

TYPE

+     This is a variable that describes +the kind of +project that is being compiled.  Knowing the type of project is +necessary +because it controls some elements of the compilation and also of the +final +promotion of the compiled products.  There are three TYPEs +supported +so far: + + +Projects of the "library" type will follow the special  +rules for +their include directory (which is created as a copy of headers in the +library +directory).  Library projects will also have their final products +copied to the lib or dll subdirectories of the build directory being +created.  +Projects that are "application"s will have their executables copied to +the executable directory in the build.  And "test" projects will +be +promoted to a subdirectory named after the PROJECT that resides under +the +test hierarchy in the build. + +

C++ Directory Structure +Variables

+

BASE_OUTPUT_PATH

+     This is the parent directory +for object files generated for the specified type of CPU and the style +of +build (e.g. debug or release builds).
+ +

CPU_BUILD_DIR

+     This variable can be used to +distinguish +directory +names used for output.  It includes the cpu name and the type of +build. + +

DYNAMIC_LIBRARY_DIR

+     The directory where dynamic +libraries will be +stored after creation.
+ +

EXECUTABLE_DIR

+     The directory where executable files +will be +stored after creation.
+ +

FINAL_DIR

+     This is the name of the directory +where the +finished +compilation products are stored, currently only import libraries for +dynamic libraries.  +It is usually a directory under the OUTPUT_PATH named "final". + +

HEADER_SEARCH_PATH

+     This is a list of directories that +will be +searched +for C++ header files (files ending in ‘.h’). + +

HOOPLE_HEADERS

+     The two standard places to look for +headers +(the repository and the third party directory) are listed in this +variable. + +

HOOPLE_LIBRARIES

+     This is where our libraries are +located.  It is usually a subdirectory called "lib" under the +repository +directory. + +

LIBRARY_SEARCH_PATH

+     This is a list of directories that +will be +searched +for C++ library archives (files ending in ".a" or ".lib"). + +

LOCAL_HEADERS

+     This variable provides a way to +include +headers +prior to the default locations in the search path.  For example, +if +you are compiling locally and have some headers that are not present in +the build you are using, then you can specify where they are in this +variable. + +

LOCAL_LIBRARIES

+     This variable allows other library +directories +to be added prior to the default search locations.  This enables +substitute +static or import libraries to be used instead of the standard ones +present +in the build. + +

STATIC_LIBRARY_DIR

+     This is the location where code +libraries are +to be copied during promotion and where they are to be searched for +when +listed in LOCAL_LIBS_USED.  Under Unix, these libraries have a +‘.a’ +suffix and are created with the "ar" program.  Under Win32, +these +libraries have a ‘.lib’ suffix and are created with "link". + +

OBJECT_DIR

+     This is where object files will be +stored +during +compilation for the target type being produced. + +

OUTPUT_DIRECTORY_LIST

+     This is a list of directories that +need to be +created under the OUTPUT_PATH.  It contains the "final" directory +where all finished products are stored, as well as all the intermediate +directories for objects. + +

OUTPUT_PATH

+     This is the temporary file storage +area.  +Any files that are created during the compilation process will be +stored +under here in a subdirectory named after the PROJECT. + +

OUTPUT_ROOT

+     This specifies the root portion of +the +OUTPUT_PATH.  +It lets a PC build use drive letters for the root, while a Unix build +can +specify a directory hierarchy. + +

SEARCH_DIRS

+     This is a list of directories that +will be +searched +for both C++ header files and for C++ code libraries.  The items +placed +on SEARCH_DIRS will be added to both the LIBRARY_SEARCH_PATH and the +HEADER_SEARCH_PATH.  +The reasoning behind this variable is lost in antiquity. + +

TESTS_DIR
+

+     The directory where test programs +will be +stored after creation.
+ +

THIRD_PARTY_DIR

+     Third party components are sometimes +used in +the +creation of products.  The directory is expected to have a +structure +containing "include" and "lib" subdirectories where headers and +libraries +are stored. + +

Compiler Dependent Flags

+

+CC

+     This is the name of the C++ compiler +executable. + +

COMPILER_HEADER_DIR

+     This is where the compiler's header +(or +include) +root directory is located.  It is usually based on the root +directory. + +

COMPILER_LIBRARY_DIR

+     This is where the code libraries for +the +compiler +are located.  It is usually based on the root directory. + +

COMPILER_ROOT_DIR

+     This should automatically be set to +the +appropriate +local directory where the C++ compiler is located. + +

CREATE_LIBRARY_FLAG

+     This flag, if required, specifies +the text +that +must precede the name of a library to create.  It is passed to the +library creation tool. + +

DEF_FILE

+     This flag only applies to Win32 +programs.  +It specifies the name of a DEF file for all of the products created in +the project. + +

LIB_PREFIX & LIB_SUFFIX

+     The portions of a library's name +dictated by the operating system.  For example, on Unix the prefix +is "lib" +and the suffix is ".a", leading to library names like "libbasis.a" for +the +basis library.  On win32, the prefix is "" and the suffix is +".lib", leading +to library names like "basis.lib".
+ +

LIBRARY_NAME_FLAG

+     This flag contains the text that +specifies a +library +that will be included in a link.  It is often "-l". + +

LIBRARY_PATH_FLAG

+     This flag provides the text needed +to add +another +library search path.  Multiple occurrences of this flag followed +by +a directory name are allowed by most compilers. + +

LIBRARY_TOOL

+     This is the name of the program +responsible +for +creating libraries. + +

LINK_TOOL

+     This is the name of the program that +links.  +This is sometimes the same as the compiler (CC) and sometimes the same +as the librarian (LIBRARY_TOOL). + +

LINKER_OPTION_SEPARATOR

+     In some compilers, linker options +need to be +separated +from compiler options that occur on the same command line.  This +flag +serves that purpose. + +

LINKER_OUTPUT_FLAG

+     This flag is sometimes required by a +linker +for +specifying the name of the library or executable that it is creating. + +

OBJECT_NAME_FLAG

+     This flag is used to specify the +name of an +object +file being created.  It is passed to the compiler to override +whatever +default name would be used. + +

Microsoft-Visual C++ Only
+

+

USE_MFC

+     This flag only applies to Visual C++ +and +indicates +that MFC is to be used in creating this project.  This is usually +the case for GUI applications. + +

VC_ROOT

+     This is an override that allows the +compiler +root +directory to be customized without changing the  code.  If +VC_ROOT +is set (either in a makefile or as an external variable), then it will +be used in place of the COMPILER_ROOT_DIR.  The best way to use +this +override is as an external environment variable; this allows makefiles +to remain the same despite your local configuration of the compiler. +
+     Note that this variable should use +forward-slashes, +where DOS/Win32 would use backslashes.  Also, if you have +installed +Visual C++ in a directory path containing space characters, then please +use the 8.3 notation for the directories containing the spaces; this +allows +the name to be passed around successfully.  For example... + +
+ + + + + + + + + + + + + + + + + + + + +
+
If Visual C++ Is Installed In
+ 		+
Then VC_ROOT Should Be
+
+
c:\devstudio\vc
+ 		+
c:/devstudio/vc
+
+
c:\program files\devstudio\vc
+ 		+
c:/progra~1/devstudio/vc
+
+
+

VCS_ROOT

+     Similarly to the VC_ROOT, this +variable points +at the root of the C# support for Visual Studio.Net.
+ +

FRAMEWORK_DIR

+     This variable specifies the location +of the +.Net framework directory.  On MS-Windows XP, the default should be +fine.  For MS-Windows 2000 or other Win32 OSes, the windows +directory +should be "winnt" instead.  If the operating system is configured +in a non-default way, the framework directory can be specified in an +environment variable.
+ +

VCPP_USE_BASE

+     Specifies that standard Win32 +libraries should +be linked in.
+ +

VCPP_USE_GUI

+     Specifies that the MFC libraries +should be +linked in. + +

VCPP_USE_OLE

+     Specifies that the COM / OLE +libraries should +be linked in. + +

VCPP_USE_RPC

+     Specifies that the MS-RPC libraries +should be +linked in.
+ +

VCPP_USE_SOCK

+     Specifies that the MS-WinSock +libraries should +be linked in.
+ +

C++ Specific Rules

+     These types of targets have one +thing in +common; +if any of the items that a target depends on in SOURCE or +LOCAL_LIBS_USED +or included files or whatever have changed since the last time the +target +was created, then it is recompiled. + +

%.bad

+     Causes the make to die.  This +is added when an incorrect file type is spotted in a list of targets.
+ +

%.dll

+     These create dynamically linked +libraries from +the SOURCE. + +

%.elf

+     Creates elf-formatted binaries for +use with a +firmware build (a specialized RTOS is the only one currently supported).
+ +

%.exe

+     This creates an executable program +using all +of +the objects and libraries specified.  It is therefore important in +a  makefile to only have executables that depend on the same group +of object files.  The hidden agenda in the "exe" type of target is +that a file ending in ".cpp" must exist; this is taken as the root of +the +executable.  It should usually contain the main() function (or its +equivalent). + +

%.lib

+     This creates static libraries from +the files +listed +in OBJECTS. + +

%.nil

+     A blank target for test compiles.
+ +

%.obj

+     These create object files from C++ +source +files +(files ending in .c or .cpp). + +

%.res

+     These create compiled resource files +from RC +files +in the SOURCE list. + +

C++ Specific Targets

+

+check_requirements

+     This target ensures that certain +characteristics +of the makefile are present.  It complains and aborts the make if +they are missing. + +

post_compilation

+     This target finalizes the +compilation by +running +the postconditions script.  If PROMOTE is true, then the final +products +are copied into the repository. + +

pre_compilation

+     This target executes the +preconditions script +to set up the compilation's output directories. + +

rebuild

+     This target performs the actions of +rebuilding.  +This mainly involves touching all of the files in SOURCE before the +compilation +has really started. + +

C++ Specific Files

+ +

postconditions.sh

+     After a compilation has succeeded, +the +postconditions +script performs the final actions required.  The nature of these +actions +depends on the type of project being made.  For a library project, +the script copies the headers to the project's include directory and +copies +libraries to the appropriate locations.  For application and test +program targets, the script copies the final products to the +appropriate +repository directory. + +

preconditions.sh

+     Before any targets are compiled, the +preconditions +script ensures that the appropriate output directories exist for the +project.  +The script also calls the version utilities to update the project's +version +file and to create any required resource files.
+ +

rebuild_oldies.sh

+     Used for compilers that support +multiple code +files +in one invocation.  This is launched to compile a batch of sources +and +catch any errors.
+ +
+
+

CLAM Example Makefiles

+
+     These examples show some common +patterns for +how  is used.  The makefiles below are actually used in real +software +projects. + +

Library-Only Makefile

+This example creates a dynamic library. + + +The dynamic library created here is mechanisms.dll.  The +basis +library is linked +in also.  The file "roller.cpp" will also be copied to the build +directory's +include path, presumably since it is a template code file. + +

Library Plus Executable Makefile

+This example shows the basis makefile with a couple of test +programs +also +being generated. + + +Note that the executables +"t_string.exe" and "t_alloc.exe" require files called "t_string.cpp" +and +"t_alloc.cpp" to exist.  These files are expected to contain the +"main()" +or "WinMain()" functions (or the MFC application object).  All of +the +files in the SOURCE variable will be included in each final executable. + +

Executable-Only Makefile

+This example is produces several test programs that exercise +the +associated +library. + + +The programs "t_alloc.exe" and so on will require C++ files +with the +same +prefix (t_alloc.cpp) to contain the main program (as in the previous +example).  +The items in the SOURCE list will be included in each executable, and +the +basis library will be linked in. + +

CLAM Hints

+     This section +is devoted to untangling snags that have been encountered in the +past.  +Hopefully problems you encounter will be discussed here.  Please +contribute +any new problems found to the library +administrator. + +

Problem:

+     A message like: + + +is displayed during a make. + +

Solution:

+     The most frequent reason for +receiving a +message +similar to the above is that there is a file listed in SOURCE that +either +does not exist or that is capitalized differently from how it is +listed.  +Check that all the files in SOURCE are in the makefile's directory and +that the exact spelling of those files (including their case) is +correct. +
+     Another potential cause of this problem is +if a file is included in the SOURCE that  does not +recognize.  +The standard compilable files are supported (*.cpp, *.c, *.rc), but it +is possible that a makefile must handle a non-standard extension (such +as *.idl).  Either the user's makefile must supply a rule for +processing +this type of file or the user must negotiate with the  +administrator +to get that type of target added to the  support. + +

Problem:

+      Clam is complaining about programs +not being +found +during a build. + +

Solution:

+     The most frequent cause of this +problem is a +directory +not being on your path.  The compilation tools bin (~/hoople/bin) +directory must be in +the PATH variable. +
+     Problems are occasionally seen when the PATH +contains directory names that have spaces in them.  Try using the +shorter 8.3 form of the directory name. +
+     An even more obscure situation sometimes +occurs: paths with networked drives seem to somehow hide paths with +local drives that +are listed later in the PATH variable.  The cause of this is +unknown, +although it was thought to be caused by NetWare at one point.  To +fix +the situation, move the local paths before the networked ones.
+
+ +
+
+

Acknowledgements

+
+
Thanks to April Bly Monnen for the wonderful cover +art. + +

Thanks to Kevin Wika for some early help with makefiles. +

+ + +
+
+
+ + + diff --git a/doc/clam_manual/clam_root.html b/doc/clam_manual/clam_root.html new file mode 100644 index 00000000..89b9889b --- /dev/null +++ b/doc/clam_manual/clam_root.html @@ -0,0 +1,38 @@ + + + + + + + CLAM Home Page + + + +
+

clam automagic maker

+
+
+

+Tutorial and Reference Manual +
+
+GNU Make +Manual +
+
+CLAM Source +
+
+CLAM C++ Support Source +
+
+CLAM C# Support Source +
+
You can download CLAM from the hoople +site.
+Please send any comments and contributions to the +Administrator +.
+
+ + \ No newline at end of file diff --git a/doc/clam_manual/partial_cygwin_for_build.txt b/doc/clam_manual/partial_cygwin_for_build.txt new file mode 100644 index 00000000..0f33a59e --- /dev/null +++ b/doc/clam_manual/partial_cygwin_for_build.txt @@ -0,0 +1,32 @@ + +install these groups: +base - default should be okay +devel - + add make +shells - default should be okay + +optional items: +admin + add shutdown +archive + add sharutils + add zip + add unzip +devel + add cvs +editors + add gvim + add vim + add emacs +interpreters + add perl +net + add openssh +text + add less +utils + add pcre (needed by less) + add cygutils (provides cal and other useful tools) + + + diff --git a/doc/feisty_meow_dox.config b/doc/feisty_meow_dox.config new file mode 100644 index 00000000..0a041967 --- /dev/null +++ b/doc/feisty_meow_dox.config @@ -0,0 +1,1219 @@ +# Doxyfile 1.5.0 + +# This file describes the settings to be used by the documentation system +# doxygen (www.doxygen.org) for a project +# +# All text after a hash (#) is considered a comment and will be ignored +# The format is: +# TAG = value [value, ...] +# For lists items can also be appended using: +# TAG += value [value, ...] +# Values that contain spaces should be placed between quotes (" ") + +#--------------------------------------------------------------------------- +# Project related configuration options +#--------------------------------------------------------------------------- + +# The PROJECT_NAME tag is a single word (or a sequence of words surrounded +# by quotes) that should identify the project. + +PROJECT_NAME = "feisty meow concerns codebase" + +# The PROJECT_NUMBER tag can be used to enter a project or revision number. +# This could be handy for archiving the generated documentation or +# if some version control system is used. + +PROJECT_NUMBER = 2.108 + +# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) +# base path where the generated documentation will be put. +# If a relative path is entered, it will be relative to the location +# where doxygen was started. If left blank the current directory will be used. + +OUTPUT_DIRECTORY = + +# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create +# 4096 sub-directories (in 2 levels) under the output directory of each output +# format and will distribute the generated files over these directories. +# Enabling this option can be useful when feeding doxygen a huge amount of +# source files, where putting all generated files in the same directory would +# otherwise cause performance problems for the file system. + +CREATE_SUBDIRS = NO + +# The OUTPUT_LANGUAGE tag is used to specify the language in which all +# documentation generated by doxygen is written. Doxygen will use this +# information to generate all constant output in the proper language. +# The default language is English, other supported languages are: +# Afrikaans, Arabic, Brazilian, Catalan, Chinese, Chinese-Traditional, +# Croatian, Czech, Danish, Dutch, Finnish, French, German, Greek, Hungarian, +# Italian, Japanese, Japanese-en (Japanese with English messages), Korean, +# Korean-en, Lithuanian, Norwegian, Polish, Portuguese, Romanian, Russian, +# Serbian, Slovak, Slovene, Spanish, Swedish, and Ukrainian. + +OUTPUT_LANGUAGE = English + +# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will +# include brief member descriptions after the members that are listed in +# the file and class documentation (similar to JavaDoc). +# Set to NO to disable this. + +BRIEF_MEMBER_DESC = YES + +# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend +# the brief description of a member or function before the detailed description. +# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the +# brief descriptions will be completely suppressed. + +REPEAT_BRIEF = YES + +# This tag implements a quasi-intelligent brief description abbreviator +# that is used to form the text in various listings. Each string +# in this list, if found as the leading text of the brief description, will be +# stripped from the text and the result after processing the whole list, is +# used as the annotated text. Otherwise, the brief description is used as-is. +# If left blank, the following values are used ("$name" is automatically +# replaced with the name of the entity): "The $name class" "The $name widget" +# "The $name file" "is" "provides" "specifies" "contains" +# "represents" "a" "an" "the" + +ABBREVIATE_BRIEF = + +# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then +# Doxygen will generate a detailed section even if there is only a brief +# description. + +ALWAYS_DETAILED_SEC = NO + +# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all +# inherited members of a class in the documentation of that class as if those +# members were ordinary class members. Constructors, destructors and assignment +# operators of the base classes will not be shown. + +INLINE_INHERITED_MEMB = NO + +# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full +# path before files name in the file list and in the header files. If set +# to NO the shortest path that makes the file name unique will be used. + +FULL_PATH_NAMES = YES + +# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag +# can be used to strip a user-defined part of the path. Stripping is +# only done if one of the specified strings matches the left-hand part of +# the path. The tag can be used to show relative paths in the file list. +# If left blank the directory from which doxygen is run is used as the +# path to strip. + +STRIP_FROM_PATH = + +# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of +# the path mentioned in the documentation of a class, which tells +# the reader which header file to include in order to use a class. +# If left blank only the name of the header file containing the class +# definition is used. Otherwise one should specify the include paths that +# are normally passed to the compiler using the -I flag. + +STRIP_FROM_INC_PATH = + +# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter +# (but less readable) file names. This can be useful is your file systems +# doesn't support long names like on DOS, Mac, or CD-ROM. + +SHORT_NAMES = NO + +# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen +# will interpret the first line (until the first dot) of a JavaDoc-style +# comment as the brief description. If set to NO, the JavaDoc +# comments will behave just like the Qt-style comments (thus requiring an +# explicit @brief command for a brief description. + +JAVADOC_AUTOBRIEF = NO + +# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen +# treat a multi-line C++ special comment block (i.e. a block of //! or /// +# comments) as a brief description. This used to be the default behaviour. +# The new default is to treat a multi-line C++ comment block as a detailed +# description. Set this tag to YES if you prefer the old behaviour instead. + +MULTILINE_CPP_IS_BRIEF = NO + +# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented +# member inherits the documentation from any documented member that it +# re-implements. + +INHERIT_DOCS = YES + +# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce +# a new page for each member. If set to NO, the documentation of a member will +# be part of the file/class/namespace that contains it. + +SEPARATE_MEMBER_PAGES = NO + +# The TAB_SIZE tag can be used to set the number of spaces in a tab. +# Doxygen uses this value to replace tabs by spaces in code fragments. + +TAB_SIZE = 2 + +# This tag can be used to specify a number of aliases that acts +# as commands in the documentation. An alias has the form "name=value". +# For example adding "sideeffect=\par Side Effects:\n" will allow you to +# put the command \sideeffect (or @sideeffect) in the documentation, which +# will result in a user-defined paragraph with heading "Side Effects:". +# You can put \n's in the value part of an alias to insert newlines. + +ALIASES = + +# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C +# sources only. Doxygen will then generate output that is more tailored for C. +# For instance, some of the names that are used will be different. The list +# of all members will be omitted, etc. + +OPTIMIZE_OUTPUT_FOR_C = NO + +# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java +# sources only. Doxygen will then generate output that is more tailored for Java. +# For instance, namespaces will be presented as packages, qualified scopes +# will look different, etc. + +OPTIMIZE_OUTPUT_JAVA = NO + +# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want to +# include (a tag file for) the STL sources as input, then you should +# set this tag to YES in order to let doxygen match functions declarations and +# definitions whose arguments contain STL classes (e.g. func(std::string); v.s. +# func(std::string) {}). This also make the inheritance and collaboration +# diagrams that involve STL classes more complete and accurate. + +BUILTIN_STL_SUPPORT = NO + +# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC +# tag is set to YES, then doxygen will reuse the documentation of the first +# member in the group (if any) for the other members of the group. By default +# all members of a group must be documented explicitly. + +DISTRIBUTE_GROUP_DOC = NO + +# Set the SUBGROUPING tag to YES (the default) to allow class member groups of +# the same type (for instance a group of public functions) to be put as a +# subgroup of that type (e.g. under the Public Functions section). Set it to +# NO to prevent subgrouping. Alternatively, this can be done per class using +# the \nosubgrouping command. + +SUBGROUPING = YES + +#--------------------------------------------------------------------------- +# Build related configuration options +#--------------------------------------------------------------------------- + +# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in +# documentation are documented, even if no documentation was available. +# Private class members and static file members will be hidden unless +# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES + +EXTRACT_ALL = YES + +# If the EXTRACT_PRIVATE tag is set to YES all private members of a class +# will be included in the documentation. + +EXTRACT_PRIVATE = NO + +# If the EXTRACT_STATIC tag is set to YES all static members of a file +# will be included in the documentation. + +EXTRACT_STATIC = NO + +# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) +# defined locally in source files will be included in the documentation. +# If set to NO only classes defined in header files are included. + +EXTRACT_LOCAL_CLASSES = NO + +# This flag is only useful for Objective-C code. When set to YES local +# methods, which are defined in the implementation section but not in +# the interface are included in the documentation. +# If set to NO (the default) only methods in the interface are included. + +EXTRACT_LOCAL_METHODS = NO + +# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all +# undocumented members of documented classes, files or namespaces. +# If set to NO (the default) these members will be included in the +# various overviews, but no documentation section is generated. +# This option has no effect if EXTRACT_ALL is enabled. + +HIDE_UNDOC_MEMBERS = NO + +# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all +# undocumented classes that are normally visible in the class hierarchy. +# If set to NO (the default) these classes will be included in the various +# overviews. This option has no effect if EXTRACT_ALL is enabled. + +HIDE_UNDOC_CLASSES = NO + +# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all +# friend (class|struct|union) declarations. +# If set to NO (the default) these declarations will be included in the +# documentation. + +HIDE_FRIEND_COMPOUNDS = NO + +# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any +# documentation blocks found inside the body of a function. +# If set to NO (the default) these blocks will be appended to the +# function's detailed documentation block. + +HIDE_IN_BODY_DOCS = NO + +# The INTERNAL_DOCS tag determines if documentation +# that is typed after a \internal command is included. If the tag is set +# to NO (the default) then the documentation will be excluded. +# Set it to YES to include the internal documentation. + +INTERNAL_DOCS = NO + +# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate +# file names in lower-case letters. If set to YES upper-case letters are also +# allowed. This is useful if you have classes or files whose names only differ +# in case and if your file system supports case sensitive file names. Windows +# and Mac users are advised to set this option to NO. + +CASE_SENSE_NAMES = YES + +# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen +# will show members with their full class and namespace scopes in the +# documentation. If set to YES the scope will be hidden. + +HIDE_SCOPE_NAMES = NO + +# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen +# will put a list of the files that are included by a file in the documentation +# of that file. + +SHOW_INCLUDE_FILES = YES + +# If the INLINE_INFO tag is set to YES (the default) then a tag [inline] +# is inserted in the documentation for inline members. + +INLINE_INFO = YES + +# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen +# will sort the (detailed) documentation of file and class members +# alphabetically by member name. If set to NO the members will appear in +# declaration order. + +SORT_MEMBER_DOCS = YES + +# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the +# brief documentation of file, namespace and class members alphabetically +# by member name. If set to NO (the default) the members will appear in +# declaration order. + +SORT_BRIEF_DOCS = NO + +# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be +# sorted by fully-qualified names, including namespaces. If set to +# NO (the default), the class list will be sorted only by class name, +# not including the namespace part. +# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. +# Note: This option applies only to the class list, not to the +# alphabetical list. + +SORT_BY_SCOPE_NAME = NO + +# The GENERATE_TODOLIST tag can be used to enable (YES) or +# disable (NO) the todo list. This list is created by putting \todo +# commands in the documentation. + +GENERATE_TODOLIST = YES + +# The GENERATE_TESTLIST tag can be used to enable (YES) or +# disable (NO) the test list. This list is created by putting \test +# commands in the documentation. + +GENERATE_TESTLIST = YES + +# The GENERATE_BUGLIST tag can be used to enable (YES) or +# disable (NO) the bug list. This list is created by putting \bug +# commands in the documentation. + +GENERATE_BUGLIST = YES + +# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or +# disable (NO) the deprecated list. This list is created by putting +# \deprecated commands in the documentation. + +GENERATE_DEPRECATEDLIST= YES + +# The ENABLED_SECTIONS tag can be used to enable conditional +# documentation sections, marked by \if sectionname ... \endif. + +ENABLED_SECTIONS = + +# The MAX_INITIALIZER_LINES tag determines the maximum number of lines +# the initial value of a variable or define consists of for it to appear in +# the documentation. If the initializer consists of more lines than specified +# here it will be hidden. Use a value of 0 to hide initializers completely. +# The appearance of the initializer of individual variables and defines in the +# documentation can be controlled using \showinitializer or \hideinitializer +# command in the documentation regardless of this setting. + +MAX_INITIALIZER_LINES = 30 + +# Set the SHOW_USED_FILES tag to NO to disable the list of files generated +# at the bottom of the documentation of classes and structs. If set to YES the +# list will mention the files that were used to generate the documentation. + +SHOW_USED_FILES = YES + +# If the sources in your project are distributed over multiple directories +# then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy +# in the documentation. The default is NO. + +SHOW_DIRECTORIES = YES + +# The FILE_VERSION_FILTER tag can be used to specify a program or script that +# doxygen should invoke to get the current version for each file (typically from the +# version control system). Doxygen will invoke the program by executing (via +# popen()) the command , where is the value of +# the FILE_VERSION_FILTER tag, and is the name of an input file +# provided by doxygen. Whatever the program writes to standard output +# is used as the file version. See the manual for examples. + +FILE_VERSION_FILTER = + +#--------------------------------------------------------------------------- +# configuration options related to warning and progress messages +#--------------------------------------------------------------------------- + +# The QUIET tag can be used to turn on/off the messages that are generated +# by doxygen. Possible values are YES and NO. If left blank NO is used. + +QUIET = NO + +# The WARNINGS tag can be used to turn on/off the warning messages that are +# generated by doxygen. Possible values are YES and NO. If left blank +# NO is used. + +WARNINGS = YES + +# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings +# for undocumented members. If EXTRACT_ALL is set to YES then this flag will +# automatically be disabled. + +WARN_IF_UNDOCUMENTED = YES + +# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for +# potential errors in the documentation, such as not documenting some +# parameters in a documented function, or documenting parameters that +# don't exist or using markup commands wrongly. + +WARN_IF_DOC_ERROR = YES + +# This WARN_NO_PARAMDOC option can be abled to get warnings for +# functions that are documented, but have no documentation for their parameters +# or return value. If set to NO (the default) doxygen will only warn about +# wrong or incomplete parameter documentation, but not about the absence of +# documentation. + +WARN_NO_PARAMDOC = NO + +# The WARN_FORMAT tag determines the format of the warning messages that +# doxygen can produce. The string should contain the $file, $line, and $text +# tags, which will be replaced by the file and line number from which the +# warning originated and the warning text. Optionally the format may contain +# $version, which will be replaced by the version of the file (if it could +# be obtained via FILE_VERSION_FILTER) + +WARN_FORMAT = "$file:$line: $text" + +# The WARN_LOGFILE tag can be used to specify a file to which warning +# and error messages should be written. If left blank the output is written +# to stderr. + +WARN_LOGFILE = + +#--------------------------------------------------------------------------- +# configuration options related to the input files +#--------------------------------------------------------------------------- + +# The INPUT tag can be used to specify the files and/or directories that contain +# documented source files. You may enter file names like "myfile.cpp" or +# directories like "/usr/src/myproject". Separate the files or directories +# with spaces. + +INPUT = $(FEISTY_MEOW_DIR)/scripts $(FEISTY_MEOW_DIR)/nucleus $(FEISTY_MEOW_DIR)/octopi $(FEISTY_MEOW_DIR)/graphiq $(PRODUCTION_DIR)/setup_src + +# If the value of the INPUT tag contains directories, you can use the +# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp +# and *.h) to filter out the source-files in the directories. If left +# blank the following patterns are tested: +# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx +# *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.py + +FILE_PATTERNS = + +# The RECURSIVE tag can be used to turn specify whether or not subdirectories +# should be searched for input files as well. Possible values are YES and NO. +# If left blank NO is used. + +RECURSIVE = YES + +# The EXCLUDE tag can be used to specify files and/or directories that should +# excluded from the INPUT source files. This way you can easily exclude a +# subdirectory from a directory tree whose root is specified with the INPUT tag. + +EXCLUDE = + +# The EXCLUDE_SYMLINKS tag can be used select whether or not files or +# directories that are symbolic links (a Unix filesystem feature) are excluded +# from the input. + +EXCLUDE_SYMLINKS = NO + +# If the value of the INPUT tag contains directories, you can use the +# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude +# certain files from those directories. Note that the wildcards are matched +# against the file with absolute path, so to exclude all test directories +# for example use the pattern */test/* + +EXCLUDE_PATTERNS = "*/3rdparty/*" "*/clam_bin/*" "*/bin/*" "*/binaries/*" "*/install/*" "*/logs/*" "*/msys/*" "*/objects/*" "*/packages/*" "*/waste/*" + +# The EXAMPLE_PATH tag can be used to specify one or more files or +# directories that contain example code fragments that are included (see +# the \include command). + +EXAMPLE_PATH = + +# If the value of the EXAMPLE_PATH tag contains directories, you can use the +# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp +# and *.h) to filter out the source-files in the directories. If left +# blank all files are included. + +EXAMPLE_PATTERNS = + +# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be +# searched for input files to be used with the \include or \dontinclude +# commands irrespective of the value of the RECURSIVE tag. +# Possible values are YES and NO. If left blank NO is used. + +EXAMPLE_RECURSIVE = NO + +# The IMAGE_PATH tag can be used to specify one or more files or +# directories that contain image that are included in the documentation (see +# the \image command). + +IMAGE_PATH = + +# The INPUT_FILTER tag can be used to specify a program that doxygen should +# invoke to filter for each input file. Doxygen will invoke the filter program +# by executing (via popen()) the command , where +# is the value of the INPUT_FILTER tag, and is the name of an +# input file. Doxygen will then use the output that the filter program writes +# to standard output. If FILTER_PATTERNS is specified, this tag will be +# ignored. + +INPUT_FILTER = + +# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern +# basis. Doxygen will compare the file name with each pattern and apply the +# filter if there is a match. The filters are a list of the form: +# pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further +# info on how filters are used. If FILTER_PATTERNS is empty, INPUT_FILTER +# is applied to all files. + +FILTER_PATTERNS = + +# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using +# INPUT_FILTER) will be used to filter the input files when producing source +# files to browse (i.e. when SOURCE_BROWSER is set to YES). + +FILTER_SOURCE_FILES = NO + +#--------------------------------------------------------------------------- +# configuration options related to source browsing +#--------------------------------------------------------------------------- + +# If the SOURCE_BROWSER tag is set to YES then a list of source files will +# be generated. Documented entities will be cross-referenced with these sources. +# Note: To get rid of all source code in the generated output, make sure also +# VERBATIM_HEADERS is set to NO. + +SOURCE_BROWSER = YES + +# Setting the INLINE_SOURCES tag to YES will include the body +# of functions and classes directly in the documentation. + +INLINE_SOURCES = NO + +# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct +# doxygen to hide any special comment blocks from generated source code +# fragments. Normal C and C++ comments will always remain visible. + +STRIP_CODE_COMMENTS = YES + +# If the REFERENCED_BY_RELATION tag is set to YES (the default) +# then for each documented function all documented +# functions referencing it will be listed. + +REFERENCED_BY_RELATION = YES + +# If the REFERENCES_RELATION tag is set to YES (the default) +# then for each documented function all documented entities +# called/used by that function will be listed. + +REFERENCES_RELATION = YES + +# If the REFERENCES_LINK_SOURCE tag is set to YES (the default) +# and SOURCE_BROWSER tag is set to YES, then the hyperlinks from +# functions in REFERENCES_RELATION and REFERENCED_BY_RELATION lists will +# link to the source code. Otherwise they will link to the documentstion. + +REFERENCES_LINK_SOURCE = YES + +# If the USE_HTAGS tag is set to YES then the references to source code +# will point to the HTML generated by the htags(1) tool instead of doxygen +# built-in source browser. The htags tool is part of GNU's global source +# tagging system (see http://www.gnu.org/software/global/global.html). You +# will need version 4.8.6 or higher. + +USE_HTAGS = NO + +# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen +# will generate a verbatim copy of the header file for each class for +# which an include is specified. Set to NO to disable this. + +VERBATIM_HEADERS = YES + +#--------------------------------------------------------------------------- +# configuration options related to the alphabetical class index +#--------------------------------------------------------------------------- + +# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index +# of all compounds will be generated. Enable this if the project +# contains a lot of classes, structs, unions or interfaces. + +ALPHABETICAL_INDEX = YES + +# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then +# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns +# in which this list will be split (can be a number in the range [1..20]) + +COLS_IN_ALPHA_INDEX = 5 + +# In case all classes in a project start with a common prefix, all +# classes will be put under the same header in the alphabetical index. +# The IGNORE_PREFIX tag can be used to specify one or more prefixes that +# should be ignored while generating the index headers. + +IGNORE_PREFIX = + +#--------------------------------------------------------------------------- +# configuration options related to the HTML output +#--------------------------------------------------------------------------- + +# If the GENERATE_HTML tag is set to YES (the default) Doxygen will +# generate HTML output. + +GENERATE_HTML = YES + +# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `html' will be used as the default path. + +HTML_OUTPUT = $(PRODUCTION_DIR)/code_guide + +# The HTML_FILE_EXTENSION tag can be used to specify the file extension for +# each generated HTML page (for example: .htm,.php,.asp). If it is left blank +# doxygen will generate files with .html extension. + +HTML_FILE_EXTENSION = .html + +# The HTML_HEADER tag can be used to specify a personal HTML header for +# each generated HTML page. If it is left blank doxygen will generate a +# standard header. + +HTML_HEADER = + +# The HTML_FOOTER tag can be used to specify a personal HTML footer for +# each generated HTML page. If it is left blank doxygen will generate a +# standard footer. + +HTML_FOOTER = + +# The HTML_STYLESHEET tag can be used to specify a user-defined cascading +# style sheet that is used by each HTML page. It can be used to +# fine-tune the look of the HTML output. If the tag is left blank doxygen +# will generate a default style sheet. Note that doxygen will try to copy +# the style sheet file to the HTML output directory, so don't put your own +# stylesheet in the HTML output directory as well, or it will be erased! + +HTML_STYLESHEET = + +# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes, +# files or namespaces will be aligned in HTML using tables. If set to +# NO a bullet list will be used. + +HTML_ALIGN_MEMBERS = YES + +# If the GENERATE_HTMLHELP tag is set to YES, additional index files +# will be generated that can be used as input for tools like the +# Microsoft HTML help workshop to generate a compressed HTML help file (.chm) +# of the generated HTML documentation. + +GENERATE_HTMLHELP = NO + +# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can +# be used to specify the file name of the resulting .chm file. You +# can add a path in front of the file if the result should not be +# written to the html output directory. + +CHM_FILE = + +# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can +# be used to specify the location (absolute path including file name) of +# the HTML help compiler (hhc.exe). If non-empty doxygen will try to run +# the HTML help compiler on the generated index.hhp. + +HHC_LOCATION = + +# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag +# controls if a separate .chi index file is generated (YES) or that +# it should be included in the master .chm file (NO). + +GENERATE_CHI = NO + +# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag +# controls whether a binary table of contents is generated (YES) or a +# normal table of contents (NO) in the .chm file. + +BINARY_TOC = NO + +# The TOC_EXPAND flag can be set to YES to add extra items for group members +# to the contents of the HTML help documentation and to the tree view. + +TOC_EXPAND = NO + +# The DISABLE_INDEX tag can be used to turn on/off the condensed index at +# top of each HTML page. The value NO (the default) enables the index and +# the value YES disables it. + +DISABLE_INDEX = NO + +# This tag can be used to set the number of enum values (range [1..20]) +# that doxygen will group on one line in the generated HTML documentation. + +ENUM_VALUES_PER_LINE = 4 + +# If the GENERATE_TREEVIEW tag is set to YES, a side panel will be +# generated containing a tree-like index structure (just like the one that +# is generated for HTML Help). For this to work a browser that supports +# JavaScript, DHTML, CSS and frames is required (for instance Mozilla 1.0+, +# Netscape 6.0+, Internet explorer 5.0+, or Konqueror). Windows users are +# probably better off using the HTML help feature. + +GENERATE_TREEVIEW = YES + +# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be +# used to set the initial width (in pixels) of the frame in which the tree +# is shown. + +TREEVIEW_WIDTH = 250 + +#--------------------------------------------------------------------------- +# configuration options related to the LaTeX output +#--------------------------------------------------------------------------- + +# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will +# generate Latex output. + +GENERATE_LATEX = NO + +# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `latex' will be used as the default path. + +LATEX_OUTPUT = latex + +# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be +# invoked. If left blank `latex' will be used as the default command name. + +LATEX_CMD_NAME = latex + +# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to +# generate index for LaTeX. If left blank `makeindex' will be used as the +# default command name. + +MAKEINDEX_CMD_NAME = makeindex + +# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact +# LaTeX documents. This may be useful for small projects and may help to +# save some trees in general. + +COMPACT_LATEX = NO + +# The PAPER_TYPE tag can be used to set the paper type that is used +# by the printer. Possible values are: a4, a4wide, letter, legal and +# executive. If left blank a4wide will be used. + +PAPER_TYPE = a4wide + +# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX +# packages that should be included in the LaTeX output. + +EXTRA_PACKAGES = + +# The LATEX_HEADER tag can be used to specify a personal LaTeX header for +# the generated latex document. The header should contain everything until +# the first chapter. If it is left blank doxygen will generate a +# standard header. Notice: only use this tag if you know what you are doing! + +LATEX_HEADER = + +# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated +# is prepared for conversion to pdf (using ps2pdf). The pdf file will +# contain links (just like the HTML output) instead of page references +# This makes the output suitable for online browsing using a pdf viewer. + +PDF_HYPERLINKS = NO + +# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of +# plain latex in the generated Makefile. Set this option to YES to get a +# higher quality PDF documentation. + +USE_PDFLATEX = NO + +# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode. +# command to the generated LaTeX files. This will instruct LaTeX to keep +# running if errors occur, instead of asking the user for help. +# This option is also used when generating formulas in HTML. + +LATEX_BATCHMODE = NO + +# If LATEX_HIDE_INDICES is set to YES then doxygen will not +# include the index chapters (such as File Index, Compound Index, etc.) +# in the output. + +LATEX_HIDE_INDICES = NO + +#--------------------------------------------------------------------------- +# configuration options related to the RTF output +#--------------------------------------------------------------------------- + +# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output +# The RTF output is optimized for Word 97 and may not look very pretty with +# other RTF readers or editors. + +GENERATE_RTF = NO + +# The RTF_OUTPUT tag is used to specify where the RTF docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `rtf' will be used as the default path. + +RTF_OUTPUT = rtf + +# If the COMPACT_RTF tag is set to YES Doxygen generates more compact +# RTF documents. This may be useful for small projects and may help to +# save some trees in general. + +COMPACT_RTF = NO + +# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated +# will contain hyperlink fields. The RTF file will +# contain links (just like the HTML output) instead of page references. +# This makes the output suitable for online browsing using WORD or other +# programs which support those fields. +# Note: wordpad (write) and others do not support links. + +RTF_HYPERLINKS = NO + +# Load stylesheet definitions from file. Syntax is similar to doxygen's +# config file, i.e. a series of assignments. You only have to provide +# replacements, missing definitions are set to their default value. + +RTF_STYLESHEET_FILE = + +# Set optional variables used in the generation of an rtf document. +# Syntax is similar to doxygen's config file. + +RTF_EXTENSIONS_FILE = + +#--------------------------------------------------------------------------- +# configuration options related to the man page output +#--------------------------------------------------------------------------- + +# If the GENERATE_MAN tag is set to YES (the default) Doxygen will +# generate man pages + +GENERATE_MAN = NO + +# The MAN_OUTPUT tag is used to specify where the man pages will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `man' will be used as the default path. + +MAN_OUTPUT = man + +# The MAN_EXTENSION tag determines the extension that is added to +# the generated man pages (default is the subroutine's section .3) + +MAN_EXTENSION = .3 + +# If the MAN_LINKS tag is set to YES and Doxygen generates man output, +# then it will generate one additional man file for each entity +# documented in the real man page(s). These additional files +# only source the real man page, but without them the man command +# would be unable to find the correct page. The default is NO. + +MAN_LINKS = NO + +#--------------------------------------------------------------------------- +# configuration options related to the XML output +#--------------------------------------------------------------------------- + +# If the GENERATE_XML tag is set to YES Doxygen will +# generate an XML file that captures the structure of +# the code including all documentation. + +GENERATE_XML = NO + +# The XML_OUTPUT tag is used to specify where the XML pages will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `xml' will be used as the default path. + +XML_OUTPUT = xml + +# The XML_SCHEMA tag can be used to specify an XML schema, +# which can be used by a validating XML parser to check the +# syntax of the XML files. + +XML_SCHEMA = + +# The XML_DTD tag can be used to specify an XML DTD, +# which can be used by a validating XML parser to check the +# syntax of the XML files. + +XML_DTD = + +# If the XML_PROGRAMLISTING tag is set to YES Doxygen will +# dump the program listings (including syntax highlighting +# and cross-referencing information) to the XML output. Note that +# enabling this will significantly increase the size of the XML output. + +XML_PROGRAMLISTING = YES + +#--------------------------------------------------------------------------- +# configuration options for the AutoGen Definitions output +#--------------------------------------------------------------------------- + +# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will +# generate an AutoGen Definitions (see autogen.sf.net) file +# that captures the structure of the code including all +# documentation. Note that this feature is still experimental +# and incomplete at the moment. + +GENERATE_AUTOGEN_DEF = NO + +#--------------------------------------------------------------------------- +# configuration options related to the Perl module output +#--------------------------------------------------------------------------- + +# If the GENERATE_PERLMOD tag is set to YES Doxygen will +# generate a Perl module file that captures the structure of +# the code including all documentation. Note that this +# feature is still experimental and incomplete at the +# moment. + +GENERATE_PERLMOD = NO + +# If the PERLMOD_LATEX tag is set to YES Doxygen will generate +# the necessary Makefile rules, Perl scripts and LaTeX code to be able +# to generate PDF and DVI output from the Perl module output. + +PERLMOD_LATEX = NO + +# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be +# nicely formatted so it can be parsed by a human reader. This is useful +# if you want to understand what is going on. On the other hand, if this +# tag is set to NO the size of the Perl module output will be much smaller +# and Perl will parse it just the same. + +PERLMOD_PRETTY = YES + +# The names of the make variables in the generated doxyrules.make file +# are prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX. +# This is useful so different doxyrules.make files included by the same +# Makefile don't overwrite each other's variables. + +PERLMOD_MAKEVAR_PREFIX = + +#--------------------------------------------------------------------------- +# Configuration options related to the preprocessor +#--------------------------------------------------------------------------- + +# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will +# evaluate all C-preprocessor directives found in the sources and include +# files. + +ENABLE_PREPROCESSING = YES + +# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro +# names in the source code. If set to NO (the default) only conditional +# compilation will be performed. Macro expansion can be done in a controlled +# way by setting EXPAND_ONLY_PREDEF to YES. + +MACRO_EXPANSION = NO + +# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES +# then the macro expansion is limited to the macros specified with the +# PREDEFINED and EXPAND_AS_DEFINED tags. + +EXPAND_ONLY_PREDEF = NO + +# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files +# in the INCLUDE_PATH (see below) will be search if a #include is found. + +SEARCH_INCLUDES = YES + +# The INCLUDE_PATH tag can be used to specify one or more directories that +# contain include files that are not input files but should be processed by +# the preprocessor. + +INCLUDE_PATH = + +# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard +# patterns (like *.h and *.hpp) to filter out the header-files in the +# directories. If left blank, the patterns specified with FILE_PATTERNS will +# be used. + +INCLUDE_FILE_PATTERNS = + +# The PREDEFINED tag can be used to specify one or more macro names that +# are defined before the preprocessor is started (similar to the -D option of +# gcc). The argument of the tag is a list of macros of the form: name +# or name=definition (no spaces). If the definition and the = are +# omitted =1 is assumed. To prevent a macro definition from being +# undefined via #undef or recursively expanded use the := operator +# instead of the = operator. + +PREDEFINED = $(DEFINITIONS) + +# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then +# this tag can be used to specify a list of macro names that should be expanded. +# The macro definition that is found in the sources will be used. +# Use the PREDEFINED tag if you want to use a different macro definition. + +EXPAND_AS_DEFINED = + +# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then +# doxygen's preprocessor will remove all function-like macros that are alone +# on a line, have an all uppercase name, and do not end with a semicolon. Such +# function macros are typically used for boiler-plate code, and will confuse +# the parser if not removed. + +SKIP_FUNCTION_MACROS = YES + +#--------------------------------------------------------------------------- +# Configuration::additions related to external references +#--------------------------------------------------------------------------- + +# The TAGFILES option can be used to specify one or more tagfiles. +# Optionally an initial location of the external documentation +# can be added for each tagfile. The format of a tag file without +# this location is as follows: +# TAGFILES = file1 file2 ... +# Adding location for the tag files is done as follows: +# TAGFILES = file1=loc1 "file2 = loc2" ... +# where "loc1" and "loc2" can be relative or absolute paths or +# URLs. If a location is present for each tag, the installdox tool +# does not have to be run to correct the links. +# Note that each tag file must have a unique name +# (where the name does NOT include the path) +# If a tag file is not located in the directory in which doxygen +# is run, you must also specify the path to the tagfile here. + +TAGFILES = + +# When a file name is specified after GENERATE_TAGFILE, doxygen will create +# a tag file that is based on the input files it reads. + +GENERATE_TAGFILE = + +# If the ALLEXTERNALS tag is set to YES all external classes will be listed +# in the class index. If set to NO only the inherited external classes +# will be listed. + +ALLEXTERNALS = NO + +# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed +# in the modules index. If set to NO, only the current project's groups will +# be listed. + +EXTERNAL_GROUPS = YES + +# The PERL_PATH should be the absolute path and name of the perl script +# interpreter (i.e. the result of `which perl'). + +PERL_PATH = /usr/bin/perl + +#--------------------------------------------------------------------------- +# Configuration options related to the dot tool +#--------------------------------------------------------------------------- + +# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will +# generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base +# or super classes. Setting the tag to NO turns the diagrams off. Note that +# this option is superseded by the HAVE_DOT option below. This is only a +# fallback. It is recommended to install and use dot, since it yields more +# powerful graphs. + +CLASS_DIAGRAMS = YES + +# If set to YES, the inheritance and collaboration graphs will hide +# inheritance and usage relations if the target is undocumented +# or is not a class. + +HIDE_UNDOC_RELATIONS = YES + +# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is +# available from the path. This tool is part of Graphviz, a graph visualization +# toolkit from AT&T and Lucent Bell Labs. The other options in this section +# have no effect if this option is set to NO (the default) + +HAVE_DOT = YES + +# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for each documented class showing the direct and +# indirect inheritance relations. Setting this tag to YES will force the +# the CLASS_DIAGRAMS tag to NO. + +CLASS_GRAPH = YES + +# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for each documented class showing the direct and +# indirect implementation dependencies (inheritance, containment, and +# class references variables) of the class with other documented classes. + +COLLABORATION_GRAPH = YES + +# If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for groups, showing the direct groups dependencies + +GROUP_GRAPHS = YES + +# If the UML_LOOK tag is set to YES doxygen will generate inheritance and +# collaboration diagrams in a style similar to the OMG's Unified Modeling +# Language. + +UML_LOOK = NO + +# If set to YES, the inheritance and collaboration graphs will show the +# relations between templates and their instances. + +TEMPLATE_RELATIONS = NO + +# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT +# tags are set to YES then doxygen will generate a graph for each documented +# file showing the direct and indirect include dependencies of the file with +# other documented files. + +INCLUDE_GRAPH = YES + +# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and +# HAVE_DOT tags are set to YES then doxygen will generate a graph for each +# documented header file showing the documented files that directly or +# indirectly include this file. + +INCLUDED_BY_GRAPH = YES + +# If the CALL_GRAPH and HAVE_DOT tags are set to YES then doxygen will +# generate a call dependency graph for every global function or class method. +# Note that enabling this option will significantly increase the time of a run. +# So in most cases it will be better to enable call graphs for selected +# functions only using the \callgraph command. + +CALL_GRAPH = NO + +# If the CALLER_GRAPH and HAVE_DOT tags are set to YES then doxygen will +# generate a caller dependency graph for every global function or class method. +# Note that enabling this option will significantly increase the time of a run. +# So in most cases it will be better to enable caller graphs for selected +# functions only using the \callergraph command. + +CALLER_GRAPH = NO + +# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen +# will graphical hierarchy of all classes instead of a textual one. + +GRAPHICAL_HIERARCHY = YES + +# If the DIRECTORY_GRAPH, SHOW_DIRECTORIES and HAVE_DOT tags are set to YES +# then doxygen will show the dependencies a directory has on other directories +# in a graphical way. The dependency relations are determined by the #include +# relations between the files in the directories. + +DIRECTORY_GRAPH = YES + +# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images +# generated by dot. Possible values are png, jpg, or gif +# If left blank png will be used. + +DOT_IMAGE_FORMAT = png + +# The tag DOT_PATH can be used to specify the path where the dot tool can be +# found. If left blank, it is assumed the dot tool can be found in the path. + +DOT_PATH = /usr/bin + +# The DOTFILE_DIRS tag can be used to specify one or more directories that +# contain dot files that are included in the documentation (see the +# \dotfile command). + +DOTFILE_DIRS = + +# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the +# graphs generated by dot. A depth value of 3 means that only nodes reachable +# from the root by following a path via at most 3 edges will be shown. Nodes +# that lay further from the root node will be omitted. Note that setting this +# option to 1 or 2 may greatly reduce the computation time needed for large +# code bases. Also note that a graph may be further truncated if the graph's +# image dimensions are not sufficient to fit the graph (see MAX_DOT_GRAPH_WIDTH +# and MAX_DOT_GRAPH_HEIGHT). If 0 is used for the depth value (the default), +# the graph is not depth-constrained. + +MAX_DOT_GRAPH_DEPTH = 0 + +# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent +# background. This is disabled by default, which results in a white background. +# Warning: Depending on the platform used, enabling this option may lead to +# badly anti-aliased labels on the edges of a graph (i.e. they become hard to +# read). + +DOT_TRANSPARENT = NO + +# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output +# files in one run (i.e. multiple -o and -T options on the command line). This +# makes dot run faster, but since only newer versions of dot (>1.8.10) +# support this, this feature is disabled by default. + +DOT_MULTI_TARGETS = NO + +# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will +# generate a legend page explaining the meaning of the various boxes and +# arrows in the dot generated graphs. + +GENERATE_LEGEND = YES + +# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will +# remove the intermediate dot files that are used to generate +# the various graphs. + +DOT_CLEANUP = YES + +#--------------------------------------------------------------------------- +# Configuration::additions related to the search engine +#--------------------------------------------------------------------------- + +# The SEARCHENGINE tag specifies whether or not a search engine should be +# used. If set to NO the values of all tags below this one will be ignored. + +SEARCHENGINE = NO diff --git a/doc/feisty_meow_quick_start.txt b/doc/feisty_meow_quick_start.txt new file mode 100644 index 00000000..6d24456b --- /dev/null +++ b/doc/feisty_meow_quick_start.txt @@ -0,0 +1,74 @@ + +Feisty Meow Concerns Ltd. is a small software shop that concentrates on building high quality, +portable, open source projects in a variety of languages (primarily bash, perl, python, C++, +and Java). Here are some highlights of our main products: + + Bookmark Processing Tools - can take a mozilla bookmark file or arbitrary + web page and extract all the links out of it, building a csv database of + web links. Using that database, a variety of output formats are + provided, including one that outputs a mozilla bookmark file again. + The most useful feature is probably the marks checker that operates on + our csv format and that locates all unreachable links in the file and + separates them out. + + CROMP protocol - supports transmission of objects across the network and + provides a platform independent method for RPC and other types of + communication. + + Octopus design pattern - the underpinning of the CROMP protocol. An octopus + has an arbitrary number of tentacles (no, not just eight) which are each + responsible for consuming a different type of object (or datum). + + Fast Templates and Portable Abstractions - the class libraries of Feisty Meow + provide numerous different data structures and programming language + abstractions (like threads and state machines). There are also some + fairly ancient templates (in use since late 80s) which in many cases + perform faster than their STL analogues. + + CLAM System - Feisty Meow is the home site of the CLAM makefile system. The + CLAM system is a flexible and extensible method for building C++ and + C# files using makefiles. + +Prerequisites: + + Software required to compile under Linux: + curl-devel + openmotif-devel + openssl-devel + wxGTK-devel + + Software required to compiler under MS-windows: + The free Microsoft compiler should build Feisty Meow but it is untested. + The full version of MS Visual Studio 2010 (version 10) is supported. + Gnu C++ should compile Feisty Meow but it is also untested recently. + +Quick Start: + + Run the following commands to bootstrap the Feisty Meow libraries, once you + have downloaded the archive or retrieved them via CVS (assuming that you + have stored the files in ~/feisty_meow): + + bash ~/feisty_meow2/scripts/generator/bootstrap_build.sh + + This should create the 'makedep' dependency checking tool and the version + tagging tool and then go through the rest of the build. + + Once you've got a bootstrapped build, you can clean out all the files with: + + bash ~/feisty_meow2/scripts/generator/whack_build.sh clean + + And if you want to load the build environment for doing makes inside the + feisty_meow hierarchies, you can either run a sub-shell with the environment: + + bash ~/feisty_meow2/scripts/generator/build_variables.sh + + or you can load them into the current shell: + + bv=~/feisty_meow2/scripts/generator/build_variables.sh; source $bv $bv + + (The double reference is required since a sourced script does not get any of + the command-line parameters from the parent script.) + + More information is available at the official site http://feistymeow.org + + diff --git a/doc/fmc_header.java b/doc/fmc_header.java new file mode 100644 index 00000000..df8f7801 --- /dev/null +++ b/doc/fmc_header.java @@ -0,0 +1,12 @@ + +////////////// +// Name : {class name} +// Author : {your name} +// Rights : Copyright (c) 2012-$now By Feisty Meow Concerns, Ltd. +////////////// +// This script is free software; you can modify/redistribute it under the terms +// of the GNU General Public License. [ http://www.gnu.org/licenses/gpl.html ] +// Feel free to send updates to: [ fred@feistymeow.org ] +////////////// + + diff --git a/doc/gnu_header.h b/doc/gnu_header.h new file mode 100644 index 00000000..4c3eb2e1 --- /dev/null +++ b/doc/gnu_header.h @@ -0,0 +1,26 @@ +#ifndef {NAME}_CLASS +#define {NAME}_CLASS + +////////////// +// Name : {class name} +// Author : {your name} +// Rights : Copyright (c) 2012-$now By Author +////////////// +// This file is free software; you can modify/redistribute it under the terms +// of the GNU General Public License. [ http://www.gnu.org/licenses/gpl.html ] +// Feel free to send updates to: [ fred@gruntose.com ] +////////////// + +//! brief description goes here. +/*! + detailed description goes here. +*/ + +////////////// + +// class definition goes here....... + +////////////// + +#endif + diff --git a/doc/makefile b/doc/makefile new file mode 100644 index 00000000..ae493d94 --- /dev/null +++ b/doc/makefile @@ -0,0 +1,17 @@ + +export DEFINITIONS + # ensure that the macros get passed down to the subprocesses. + +include cpp/variables.def + +PROJECT = Source_Documentation +TYPE = application +FIRST_TARGETS = build_doxygen +CLEANUPS = html + +include cpp/rules.def + +build_doxygen: + @echo the defs are $(DEFINITIONS) + doxygen $(wildcard *.config) + diff --git a/doc/perl_tools.html b/doc/perl_tools.html new file mode 100644 index 00000000..5c2c932e --- /dev/null +++ b/doc/perl_tools.html @@ -0,0 +1,372 @@ + + + + + + + + + YETIcode Perl Scripts + + + + +

 

+
+ + + + + + +
+
+

YETIcode Open Source Perl +Scripts

+

Some Hopefully Useful GPL-Licensed Perl Code
+

+
+
Contributed by Chris Koeritz (Koeritz@Gruntose.COM)
+See the GNU Public +License for details of licensing.
+
+

Caveats:

+
    +
  1. No warranty, express, implied or imagined, is offered for +these files.  If you destroy your life by running one of them, I +will have sympathy, but that's about it.
    2. +
  2. Some of these shell scripts depend on environment variables.  +The most frequent case of this is FEISTY_MEOW_DIR, which should point to the +top-level +directory where the YETIcode scripts are stored on your +machine.   This variable is set by default when the scripts are in +the ~/yeti folder.  Consult your operating +system documentation if you are +unfamiliar with the concept or management of environment variables.
    3. +
  3. These files are provided as possibly useful shell scripts +rather than as full-fledged reusable and object oriented components.
    4. +
  4. Improvements and contributions are gladly accepted.  +They will be processed as fast as our schedule permits.  Please +send any changes to the Gruntose Curator at fred@gruntose.com .
    5. +
  5. These files are mostly portable between Unix and the +various Windoze OSes, but in many cases you may want to fix the +defaults or path names to make them more suitable for your own needs.
    6. +
  6. Some of the scripts invoke external programs that are +available for most Unixes.  For Windoze users, a set of GNU Unix +utilities is available at "http://www.mingw.org/".
    7. +
  7. An alternative, but not recommended, GNU suite is +at "http://www.cygwin.com/".
    8. +
  8. Direct Cognition: +View the scripts directory itself rather than navigating with the links +below: scripts.
    9. +
+
+
+

 

+
+ + + + + + +
+

Library Files
+

+
+

diff_lib.pl

+
The "differ" utilities can be used to compare two +directories of text or binary files against each other.  The two +directories are presumably close in contents.  This can be useful +when one is revising a set of files and wants to synchronize an older +copy against a newer version.  Support for "differ.pl" +is provided +here.
+

filename_helper.pl

+
Contains a handy set of utilities for manipulating +filenames.  These can help to make perl scripts portable across +the two well-known types of filename separators ('/' and '\').  +They also provide support for ripping up filenames into their +components.
+

inc_num.pl

+
This is a simple utility that manages a file with a +number in it.  This is somewhat more useful than it sounds.  +Functions are provided to get the current number and to change the +number.
+

+

shared_snarfer.pl

+
This library supports the "snarf" utilities.  +The +utilities manipulate archive files with the ".snarf" extension.  +These +packed +snarf files are compressed chunks of directory hierarchies.  Bob +files +are useful because they track a number per distinct "snarf" types that +is +used to make uniquely named new archives of the appropriate type.  +This +number is an ever increasing integer that's stored in a well-known +(configurable) location.  When a snarf file is unpacked (using the +"unsnarf" tool), the number is updated on the local machine so that the +next generated file will +be one greater than the previous number.  If one is travelling +between +two machines with the same snarf file, this will have the effect of +keeping +the number updated on both sides. +
+

zap_the_dir.pl

+
Support for the zapdirs utility.  This library +cleans out the directory that it is passed by removing files that are +not considered important (using "filename_helper.pl +").  The list of important files is something you might want to +look at to ensure that you won't get burned by zapdirs.
+
+
+
+

 

+
+ + + + + + +
+

Applications

+
+

add_cr.pl

+
Processes Unix format text files for pcdos by +forcing the line endings to be Carriage Return plus Line Feed (CRLF).
+

+

cgi_display.pl

+
Turns the files passed on the command line into a +stream of CGI compatible text output. The javascript show_file method +(see the +source for this page) is preferred since it is lighter weight and +doesn't +need cgi, but there are some situations where cgi is the only option +(older +browsers or requirements of no javascript).
+

+

change_endings.pl

+
Replaces the suffix of all filenames in the current +directory +with a different suffix.  Suffix here is defined as the set of +characters +after the last period ('.') in the name.  Note this will not work +for +names without suffices.
+

+

cpdiff.pl

+
Copies files from a source directory into a +destination directory.  The files are only copied when they are +missing in the destination or when the destination version has +different contents.  The syntax looks like this:
+    cpdiff  source  destination
+The assumption is that the files in the source directory are somehow +better, newer or more complete than the set of files in the destination.
+
+

cpdiffnow.pl

+
Similar to cpdiff, but this utility sets the +destination file's time stamp to "now".  This should cause the new +or changed files in the destination directory to be more recent than +anything else in there.  This is helpful sometimes for forcing +compilation of modified source files.
+
+

+

cvs_fix.pl

+
Wraps the cygwin cvs command for pcdos/win32. + Any +unfriendly backward slashes are flipped to be forward slashes.
+
+

+

differ.pl

+
Compares two directory hierarchies and the files +they +contain.  The first parameter is a directory +to compare against "this" directory; +every subdirectory "here" will be traversed in order to build the +output file that shows the differences.  An optional second +argument can be used to specify a different directory than the current +one as the source of the comparison (the first argument is always the +destination of the comparison).
+

filedump.pl

+
Collects the contents of the files whose names are +passed on the command line into one gigundo stream which is passed to +standard output. The output can be piped into another file as desired.
+

generate_aliases.pl

+
Performs some useful activities for the YETI shell +environment.  Using the environment variable for FEISTY_MEOW_SCRIPTS (which +is set in the appropriate startup files to be the shell scripts +directory, where all this stuff lives), generate_aliases will create +all of the aliases files for the combinations of operating systems and +types of shells supported.  Currently this includes Linux, Unix, +PCDOS, OS/2 and MS-WIN32 (9x, NT, 2K, XP, etc) for +supported operating systems.  The shell languages supported are +dos's command, nt's cmd, unix's sh and bash, and perl.  This script will also look for +any files ending in ".sh" or ".pl" and it will create aliases for them +in forms appropriate to the different shells.  The .zz_auto_gen +subdirectory +is created under the home directory (or under TMP in DOS and Win32) as +a storage place for the generated +files.
+

+

goodbye.pl

+
A logout script for exiting from a shell; it prints +a message using the nechung oracle for the user's benefit and starts a +byejob before exiting. The byejob will wait for a few seconds, then +clear the screen and print another fortune. It attempts to leave the +screen looking like a +standard login, but with an extra fortune.
+

+

+

new_sig.pl

+
Generates a signature file from the nechung +database +using the 'nechung' application.  See the HOOPLE library for the nechung +application. + The database for nechung resides in the whole +YETI +package in "yeti/database".
+

+

renlower.pl

+
Renames all of the files passed on the command line +such that they are only in lower-case.  Useful if you're tired of +passing mistakenly re-capitalized names from a defective 8.3 OS (e.g. +Doze95/98) to +a file system where you care about the case.
+

runner.pl

+
Finds all executable files in the current directory +(and subdirectories) and runs them.  The output of the programs is +sent to standard output.  Standard error is used to report which +file is being worked on, plus the running programs' own standard error +streams are merged into runner's standard error stream.  This +makes it nice to do something like:
+       runner >runs.log
+where the runs.log file will contain the output of each program that +was executed and the console will be sent messages as each program is +started and finished (and errors show up at the console also).
+
+

safedel.pl

+
Makes deleting files and directories a little less +nerve-wracking.  If you substitute safedel as an alias for rm or +del or deltree or whatever, it will make a zipped backup of the items +before they are actually deleted.  Safedel keeps track of a number +that is attached to each zip to enforce uniquely numbered +archives.  They are stored in a directory named "zz_del_keep" +that is stored under the temorary directory (specified by the +environment +variable named TMP).  A report of the contents of the compressed +trash +is appended to a file named "zz_safedel.rpt" in the TMP directory.  +Occasional +cleaning of the deleted files folder is recommend, but this utility has +saved +my various parts several times already.
+

+

+

snarf_linux_config.pl

+
A snarf utility that packages up the +important configuration files in a Linux installation.
+

+

snarf_light.pl

+
A selective snarf of the source hierarchy.  +This +collects the code that I manage.  As such, this is probably +irrelevant to anyone but CAK.
+

snarf_notes.pl

+
Gathers all "important" files from the home +directory. + This +is somewhat personally tuned but it includes files and directories that +have +"project", "notes", or "crucial" in their name.
+

+

snarf_src.pl

+
A source code grabbing snarfer.  The entire +source +code hierarchy is snarfed.  Note that one should edit the +hierarchy +location to make it appropriate for your local source code.
+

+

snarf_yeti.pl

+
A snarfer for the YETI shell scripts and databases.
+

summing_dir.pl

+
Offers a directory listing along with total file +sizes +and disk free space.
+
+
+

synch_build.pl

+
This is a helper utility that synchronizes the binary +outputs from a build process with an existing installed location.  Given a target directory, the executable +programs and dynamic libraries that exist there will be synchronized +with the build repository's versions.  This is kind of a quickie +upgrade process, as long as the files in the target location are not +locked by other processes.
+
+

unsnarf.pl

+
Uses the snarfer utilities to undo a previously +snarfed file.  A folder named "snarf_BASE" is created for the +contents, where BASE +is replaced with the basename of the snarf file (that is, without the +".snarf" +suffix).  The number that tracks the snarf files of this type is +updated +such that the next snarf file will be at least one higher than this +snarf's +sorta +unique number.  The number will be managed correctly if you're +always +unsnarfing the most recent snarf files before creating any new snarfs.
+

+

whack_forever.pl

+
Since all of my file deletion commands are aliases +to safedel, it is hard to actually remove a +file.  If I'm really really sure that a file or directory needs to +be +permanently deleted, then this command can be used.  It shows the +names +it is removing also, but it does _not_ ask for confirmation.
+

+

y2038_check.pl

+
Tests the system for survival +past the year 2038, which is when the Unix time scale runs out of bits +for the number of seconds since 1970 measured in a 32 bit integer.
+
+

zapdirs.pl

+
Removes empty directories and directories +containing only +unimportant crud (see "filename_helper.pl").  +If there are no arguments, then the current directory is cleaned up; +any subdirectories +will be traversed into and removed if it seems appropriate.  +Otherwise, +zapdirs operates on the arguments passed to it as if they are directory +names +to be cleaned.
+
+
+

 

+
+ + diff --git a/doc/shell_header.txt b/doc/shell_header.txt new file mode 100644 index 00000000..739bb0b9 --- /dev/null +++ b/doc/shell_header.txt @@ -0,0 +1,13 @@ +#!/bin/bash +#!/usr/bin/perl +#!/usr/bin/python +############## +# Name : {script name} +# Author : {your name} +# Rights : Copyright (C) 2012-$now by Feisty Meow Concerns, Ltd. +############## +# This script is free software; you can modify/redistribute it under the terms +# of the GNU General Public License. [ http://www.gnu.org/licenses/gpl.html ] +# Feel free to send updates to: [ fred@gruntose.com ] +############## + diff --git a/doc/text_examples/chinese_simplified_text.txt b/doc/text_examples/chinese_simplified_text.txt new file mode 100644 index 00000000..1219fd33 --- /dev/null +++ b/doc/text_examples/chinese_simplified_text.txt @@ -0,0 +1,10 @@ + +we will translate this at babelfish: + +Let us see then if we can narrow it down. As I focus my mind upon it, it seems rather less impenetrable. What indications have we as to this book? + +into this: + +让我们然后看如果我们能使它狭窄击倒。因为我聚焦我的头脑在它, 它似乎宁可较不难贯穿。什么征兆有我们至于这本书? + + diff --git a/doc/text_examples/korean_text.txt b/doc/text_examples/korean_text.txt new file mode 100644 index 00000000..52be2983 --- /dev/null +++ b/doc/text_examples/korean_text.txt @@ -0,0 +1,12 @@ + + +we will translate this at babelfish: + +Let us see then if we can narrow it down. As I focus my mind upon it, it seems rather less impenetrable. What indications have we as to this book? + +into this: + +우리들을 그때 우리가 떨어뜨리기 위하여 그것을 좁힐 수 있으면 보는 시키십시요. 나가 그것에 나의 마음을 초점을 맞추기 때문에, 오히려 보다 적게 보인다. 이 책에 관해서는 무슨 표시가 우리가 있는가? + + + diff --git a/doc/text_examples/readme.txt b/doc/text_examples/readme.txt new file mode 100644 index 00000000..0111f86c --- /dev/null +++ b/doc/text_examples/readme.txt @@ -0,0 +1,7 @@ + + +these are example files of other languages in utf-8 format. + +they can be used to test proper handling of the characters in hoople code. + + diff --git a/doc/text_examples/russian_text.txt b/doc/text_examples/russian_text.txt new file mode 100644 index 00000000..4ef6c44b --- /dev/null +++ b/doc/text_examples/russian_text.txt @@ -0,0 +1,4 @@ + +Stanislav Yevgrafovich Petrov (Russian: Станислав Евграфович Петров) (born c. 1939) is a retired Russian Strategic Rocket Forces lieutenant colonel who, on September 26, 1983, averted a potential nuclear war by refusing to believe that the United States had launched missiles against the Soviet Union, despite the indications given by his computerized early warning systems.[1] + + diff --git a/doc/text_examples/tibetan_text.txt b/doc/text_examples/tibetan_text.txt new file mode 100644 index 00000000..321ddace --- /dev/null +++ b/doc/text_examples/tibetan_text.txt @@ -0,0 +1,13 @@ + + +om mani padme hum: +ༀ'མཎི'པདེྨ'ཧཱུྃ ༔ + + +this was scarfed from a tibetan resources page: + + +༄༅།།གངས་ལྗོངས་གློག་རྡུལ་དཔེ་མཛོད་ཁང་ཞེས་པ་འདི་དེང་དུས་ཀྱི་ འཕྲུལ་རྩལ་བེད་སྤྱད་དེ་ཁ་བའི་ལྗོངས་དང་འབྲེལ་ཡོད་ཀྱི་རིག་ གཞུང་ངོ་མཚར་ཅན་རྣམས་འཛམ་གླིང་ཡུལ་གྲུ་རིས་མེད་ཀྱི་སྐྱེ་བོའི་ སྤྱན་ལམ་དུ་བསྟར་བའི་རིན་གོང་མེད་པའི་དྲ་བའི་སྟེགས་བུ་ཞིག་ ཡིན། ངེད་ཚོས་དྲ་ལམ་དེ་བརྒྱུད་སྐད་རིགས་མི་འདྲ་བའི་ཐོག་ནས་ཁུལ་ དེའི་དཔྱད་གཞིའི་ཡིག་ཆ་སྣ་ཚོགས་མཁོ་འདོན་བྱེད་ཀྱིན་ཡོད་པས་ ཚུལ་དེ་ནི་གསར + + + diff --git a/doc/uva_header.java b/doc/uva_header.java new file mode 100644 index 00000000..54b70eb7 --- /dev/null +++ b/doc/uva_header.java @@ -0,0 +1,12 @@ + +////////////// +// Name : {class name} +// Author : {your name} +// Rights : Copyright (c) 2012-$now By University of Virginia +////////////// +// This file is free software; you can modify/redistribute it under the terms +// of the Apache License v2.0: http://www.apache.org/licenses/LICENSE-2.0 +// Feel free to send updates to: [ koeritz@virginia.edu ] +////////////// + + diff --git a/docs/bash_tools.html b/docs/bash_tools.html deleted file mode 100644 index 8a0dc853..00000000 --- a/docs/bash_tools.html +++ /dev/null @@ -1,123 +0,0 @@ - - - - - - - - - YETIcode Bash Scripts - - - - -

 

-
- - - - - - -
-
-

YETIcode Open Source Bash -Scripts

-

GPL-Licensed Bash Code
-

-
-
Contributed by Chris Koeritz (Koeritz@Gruntose.COM)
-See the GNU Public -License for details of licensing.
-
-

Caveats: please refer to the Perl -Scripts page which shares the same constraints as these Bash -Scripts do.
-

- Direct Cognition: -View the scripts directory itself rather than navigating with the links -below: scripts. -
    -
-
-
-

 

-
- - - - - - -
-

Assorted Bash Script Files

-
-

uhh.sh

-
This documentation page isn't quite ready yet.
-In fact, this file is still in its very first few iterations and is -pretty -limited so far...
-
-

cvs_importer.sh

-
This script eliminates the need to use the cvs -import command to pull in a whole new sub-hierarchy.  Given a -sub-folder under an existing hierarchy, it will add all the -subdirectories and all of the files in those subdirectories.  The -script avoids adding any files found in the internally used CVS -directories.
-For example, suppose you have a folder called "hoople" that's a -top-level project in CVS.  You want to add a new folder under the -existing hierarchy "hoople/source/lib_src" called "pasta".  The -"pasta" hierarchy has hundreds of subdirectories and thousands of -files.  Assuming that you've already moved the new pasta source -folder into place, the command would be:
-    cvs_importer hoople/source/pasta
-If you don't have the Yeti aliases set up, then you may need to type -this instead:
-    bash ~/yeti/scripts/cvs_importer.sh -hoople/source/pasta
-
-

-

movie_seeker.sh -/ movie_stripper.sh -/ show_stripper.sh
-

-
Some manipulation methods for a -particular type of movie and TV show database.  These expect a db -in the form of a CSV file with three fields per line: (1) index number, -(2) show or movie name and (3) show episode title.  The third -field is defined as blank for movies.  The movie_seeker finds a -given movie (or pattern) in the database.  The movie_stripper -pulls out all the unique movie or show names in the database.  The -show_stripper pulls out the episode names for a particular show name -(or pattern).
-
-

call_movie_seeker.sh -/ call_movie_stripper.sh -/ call_show_stripper.sh
-

-
These are CGI correspondents to -the above movie database searches.  They're used on the Gruntose -web site.
-
-
-
-
-
-
-
-
-
- - diff --git a/docs/binaries_note.txt b/docs/binaries_note.txt deleted file mode 100644 index e4191f65..00000000 --- a/docs/binaries_note.txt +++ /dev/null @@ -1,22 +0,0 @@ - -There are a few pre-built binaries included with hoople. -They originate from a few different sources. Feel free to not trust them. - -These apps are external to the HOOPLE build... - -build/msys hierarchy: - This is copied directly from the msys project of MingW. - It has had zip.exe, unzip.exe and short_path.exe added to it. - - unzip.exe & zip.exe: - The zip and unzip tools are from the info-zip project. They are somewhat - antiquated but still work great on the various 32-bit windows platforms. - These utilities are self-identified as: "Zip 2.3 (November 29th 1999)" - To get a more recent version of the zip utilities or build them yourself, - they can be found at the site: http://www.info-zip.org/ - - short_path.exe: - Built by the hoople bootstrapping process, but unfortunately this tool - is desperately needed for windows builds to work nicely with clam and - bash. It can be replaced by any newer working version from the bootstrap. - diff --git a/docs/clam_manual/clam_docs.html b/docs/clam_manual/clam_docs.html deleted file mode 100644 index 2d2ec39a..00000000 --- a/docs/clam_manual/clam_docs.html +++ /dev/null @@ -1,2334 +0,0 @@ - - - - - - - CLAM Reference Manual - - -
- -

CLAM: Coordinated Librarian &

-

Automatic Maker

-
-
-
- -

Tutorial and Reference Manual

-
-
- -
By Chris Koeritz (koeritz@gruntose.com)
-
-
- -

-

-
-
- -

Table of Contents

-
-
    - -
  1. Executive Summary
    2. - -
  2. Preparing Your Computer to Use -CLAM
    3. - -
      - -
    1. Necessary Steps
      2. - -
    - -
  3. CLAM Tutorial
    4. - -
      - -
    1. Caveats
      2. - -
    2. Basics
      3. - -
    3. Common Files
      4. - -
    4. Important Variables
      5. - -
    5. Variable Assignment
      6. - -
    6. Optional Variables
      7. - -
    7. Writing Your Own Rules
      8. - -
    8. Conclusion
      9. - -
    - -
  4. CLAM Reference
    5. - -
      - -
    1. Language Independent -Variables
      2. - -
    2. Language Independent -Rules
      3. - -
    3. Language Independent -Targets
      4. - -
    4. Language Independent -Files
      5. - -
    5. C++ Specific Variables
      6. - -
        - -
      1. Directory Structure -Variables
        2. - -
      2. Compiler Dependent Flags
        3. - -
      3. Microsoft Visual C++ Only
        -
        4. - -
      4. Support for -Compilation -Extensions
        5. - -
      - -
    6. C++ Specific Rules
      7. - -
    7. C++ Specific Targets
      8. - -
    8. C++ Specific Files
      9. - -
    - -
  5. Example CLAM Makefiles
    6. - -
  6. CLAM Hints and Troubleshooting
    7. - -
  7. Acknowledgements
    8. - -
-
- -

-

-
-
- -

Executive Summary

-
-    The CLAM system is a set of macros and rules -for the GNU make program -that -simplifies the creation of executable programs and code -libraries.  -Most makefiles that use the CLAM system are ten lines long or -less.  -Makefiles are stated in terms of a set of special variable names that -CLAM -interprets in order to issue the correct sequence of compilation -directives.  -This document presents a tutorial on the variable names and simple -rules -that need to be used with CLAM.  Several example makefiles and the -full -reference manual for CLAM are also included.
-    CLAM is part of the HOOPLE libraries (http://hoople.org/) and can be -downloaded from there or through a sourceforge mirror site.
-    In the remainder of the document, we will often -refer to CLAM as just "clam".
-  - -
-

-

-
-
- -

Preparing Your Computer to Use -CLAM

-
-

Necessary Steps:

-
    - -
  1. Setting environment variables for clam:
    2. - -
      -
    1. FEISTY_MEOW_DIR:
      2. - -
        - -
      1. -**REVISE** out of date... - -This variable has been needed since clam became -part of the YETIcode project (at http://yeticode.org).
        2. - -
      2. The default location for clam is under the FEISTY_MEOW_DIR -in a -folder named clam, although the version of clam shipped with the HOOPLE -code (http://hoople.org) actually lives under the root of the hoople -hierarchy.
        -
        3. - -
      3. If the yeti root directory is in $HOME/yeti -already, then the -default for FEISTY_MEOW_DIR will work and it doesn't need to be declared.
        4. -
      4. Setting the variable:
        -
        5. - -
          - -
        1. On Unix (with the bash shell): export MAKEFLAGS="-I $HOME/yeti/clam"
          2. - -
        2. On win32: set -MAKEFLAGS="-I c:/yeti/clam"  (or set this in the System -control panel, under the advanced tab, in environment variables)
          -
          3. - -
        3. Note that the use of -forward slashes is mandatory in the clam directory in MAKEFLAGS.
          -
          4. - -
        - -
      - -
    2. MAKEFLAGS:
      3. - -
        - -
      1. This variable is required to be set in the -environment before using clam with gnu-make.  It tells make where -to find the clam definitions and scripts.
        2. - -
      2. Setting the variable:
        -
        3. - -
          - -
        1. On Unix (assuming bash as shell): export MAKEFLAGS="-I $FEISTY_MEOW_DIR/clam"
          2. - -
        2. On win32: set -MAKEFLAGS="-I %FEISTY_MEOW_DIR%/clam"
          3. - -
        3. This variable also requires forward slashes -instead of -backslashes.
          4. - -
        - -
      - -
    - -
  2. Required Tools:
    3. - -
      - -
    1. The compiler itself:
      -
      2. - -
        - -
      1. If you are running GNU/Linux (or almost any other -Posix-compliant operating system), then the GNU C/C++ compiler -suite is pretty much all that's needed.
        2. - -
      2. The -GNU C/C++ compiler (included in the MinGW -toolkit) should be all that's needed for -compilation, -but the Microsoft Visual Studio 6.0-8.0 compilers can be used if -available.  Compatibility is only guaranteed for vc8 -however.
        -
        3. - -
      - -
    2. Win32 Unix Tools:
      3. - -
        - -
      1.  If you are running a win32-based product -(windows NT, -windows -2000, -windows xp, etc) then a few additional tools are required...
        -
        2. - -
      2. The recommended GNU utilities are available for -win32 in the -MingW MSYS -package (http://www.mingw.org/).
        3. -
      3. The MSYS tools are actually included in the source safe -archive for -hoople. The version provided by hoople is recommended -because a -couple of missing tools have been added back in.
        4. -
      4. They can also be downloaded the mingw web site: MSYS -package: msys_bins.tar.gz
        5. -
      5. Note that you will need to add the -binaries -directory from MSYS -to -your path.  The PATH variable can be accessed under MS-NT type -OSes through the -"control panel | system | advanced | environment variables" menu -trail.  If you plan to use msys outside of clam, then ensure that -the MSYS bin (l:/msys/bin) directory is prior -to the -windows system directory in your path; this causes the Unix "find" -command to be used instead of the NT version.
        6. -
      6. Alternatively, a similar set of GNU utilities is -available -in the Cygwin -package, although these tools are no longer recommended and are, in -fact, actively deprecated.
        7. - -
          - -
        - -
      - -
    3. makedep and version_stamper tools:
      4. - -
        - -
      1. The hoople/bin directory in the archive has -pre-built -versions of tools used by clam during a build.
        -
        2. - -
      2. If you would rather rebuild them from source, then -running -the script "bin/bootstrap_build.sh" will -recreate all of these internal tools.
        -
        3. - -
      - -
    - -
  3. Third Party Tools Used By or Supported Within clam:
    4. - -
      - -
    1. wx widgets:
      2. - -
        - -
      1. home page: http://www.wxwidgets.org/
        2. - -
      2. As far as the clam team is concerned, this is the -premier -portable (and open source) library for graphical user interfaces.
        -
        3. - -
      - -
    2. OpenSSL:
      3. - -
        - -
      1. home page: http://www.openssl.org/
        2. - -
      2. This is the team's most favorite library for SSL -(Secure -Sockets Layer) and general encryption needs.
        -
        3. - -
      - -
    3. cURL:
      4. - -
        - -
      1. home page: http://curl.haxx.se/
        2. - -
      2. The curl library rocks(!) and provides a very -powerful set of -tools for programmatically interacting with live web pages.
        -
        3. - -
      - -
    - -
  4. Other clam Preconditions:
    5. - -
      - -
    1. Linux platforms:
      2. - -
        - -
      1. The standard source code repository is a directory -called -"hoople" -in the user's home directory.  If you decompress the hoople -library archive in your home directory, you should be all set to -perform a build.
        2. - -
      2. See the HOOPLE website for more details about -downloading that codebase (http://hoople.org).
        -
        3. - -
          - -
        - -
      - -
    2. Win32 platforms:
      3. - -
        - -
      1. The standard repository for source code is a substituted drive l:, which is where all the other hierarchies start.  This -drive can be mapped to any folder desired using the "subst" command -(for example, "subst l: c:\build_dir"). - All -objects and final products will be generated to the l: drive.
        2. - -
      2. Using MS Visual Studio as the Compiler:
        3. - -
          - -
        1. VS80COMNTOOLS/VS90COMNTOOLS/VS100COMNTOOLS variable:
          2. - -
            - -
          1. This variable should be automatically created by -Visual Studio upon installation.  If it isn't, then Microsoft has -a bug or you need to restart your current prompt or your computer.
            -
            2. -
          2. The paths that clam uses to find compiler binaries -is calculated based on this variable.
            3. -
          3. Older versions of visual studio are currently -unsupported because Microsoft constantly rearranges their folders and -tools in a non-maintainable way.
            -
            4. -
          -
        2. Several other environment variables are required -by Visual -Studio.  They can be set up for your current command prompt by -running "vcvars32.bat" or "vsvars32.bat" (found under -the -compiler's common directory, which varies depending on the version of -visual studio).
          -
          3. - -
        - -
      - -
    - -
-
- -

-

-
-
- -

CLAM Tutorial

-
-     This section provides an overview of -how clam -works and how you can make it work for you.  It is quite brief, -but -should suffice for most common cases of makefiles.  For more -detailed -usage, consult the CLAM Reference section of this document. - -

Caveats

-
    - -
  • Most of the Unix tools employed in the make process are -case-sensitive.  -This means that they will probably not find any of the clam support if -the files have been changed to upper-case names.  It also means -that -all code files must match their descriptions in makefiles, letter for -letter.  -And any batch files or executables invoked also need to be in -lower-case -as clam expects them to be.
    • - -
  • A corollary case requirement is that the makefile must -be named -either -"makefile" or "Makefile".  These are the Unix standard names and -GNU make -looks for these by default.  If you are willing to type "make -f makefile_name", -then you can run any makefile.  However, the build-ready makefiles -should be named according to the standard, since the build process will -look for these automatically.
    • - -
-

-Basics

-     The C++ Library -Automatic Maker system (or CLAM) is defined as a set of -variable -(or macro) definitions.  These variable definitions are -manipulated in -order to compile and link programs.  By setting the variables' -values -appropriately, specific products can be generated from the target rules -defined -in clam.  Both variables and rules are extensible.  The -general -procedure for building a clam-based Makefile has four user-defined -steps: - -
    - -
  1. loading the default variables for clam,
    2. - -
  2. redefining the default variables where necessary,
    3. - -
  3. loading the default rule set for clam,
    4. - -
  4. defining rules that are local to the user's Makefile.
    5. - -
-Step 4 can usually be omitted unless the project creates -components -whose types are not supported by clam.
-     clam is structured as a directory hierarchy -where the root of clam -supports -the most general makefile activities.  Activities such as -recursing -into subdirectories and providing support for cleaning up after a make -are -provided at this level.   In the remainder of the document, we -will -designate this location with a "$" character to clarify what part of -the clam hierarchy we are describing.
-     The root clam -support files are mostly language independent, since they are used by -all -varieties of language dependent derived versions of clam.  These -files -are generally not of concern unless one is designing a new derived -version -of clam for a language not yet supported.
-     The subdirectories off of the clam root -provide -"derived" makefile services, such as C++ or Ada compilation.  Each -derived clam service implements at least two files to link into the -rest of the -clam system: a variables file and a rules file.  The variables -file defines -the options for the derived make process; by changing the values of -these, -different types of targets can be created.  The rules file -implements -creation of the targets relevant to the programming language being -supported.
-     It may be worth noting that clam can be used to -drive -any kind of programmatic process--not just compilation.  Currently -though, -program compilation is the primary goal. - -

Common Files

-     The top-level file called -"$/variables.def" -contains -definitions and descriptions of the variables used throughout the clam -system.  For a non-derived type of make (using only base clam -support), -this file should be included near the start of the user's -Makefile.  -The rules file (stored in "$/rules.def") should be included after the -user -has modified the appropriate variables that will dictate how the make -is -performed. -
-     This scheme of including variables at the -top and then rules at the bottom of the user's makefile is employed in -all clam makefiles.  For example, makefiles for C++ compilation -are structured the -same way.  The user's C++ makefile includes the C++ variables -(stored -in a subdirectory called "$/cpp" under the clam root) at the top of the -makefile and then includes the C++ rules at the bottom.
-     An example -of a C++ makefile is shown below: - -
    - include cpp/variables.def
    -
    -PROJECT = basis
    -TYPE = library
    -SOURCE = chaos.cpp checkup.cpp earth_time.cpp guards.cpp istring.cpp \
    -  log_base.cpp mutex.cpp occurrence.cpp outcome.cpp -outcome_table.cpp \
    -  packable.cpp portable.cpp runtime_history.cpp -system_outcomes.cpp \
    -  utility.cpp version_checker.cpp version_record.cpp
    -TARGETS = basis.lib
    -
    -include cpp/rules.def
    -     -
-The interior of the makefile overrides the TYPE, SOURCE -and TARGETS variables for C++ compilation to specify what is to be -built -(basis.lib) and what it consists of (the CPP files mentioned in -SOURCE).  - The PROJECT variable being overridden is actually defined in the -$/variables.def; -a project name is a required feature of all clam makefiles. - -

Important Variables

-     -The clam root directory is pointed to by an internal variable called -"CLAM_DIR", -defined in $/variables.def.  This variable is used by the clam -system -to find extra files that might be needed by derived makefile -support.  -It is important to change this to the appropriate value when you are -using the system in a different location.  The CLAM_DIR variable -can either -be directly edited in $/variables.def, or it can be overridden in the -environment -of the shell running the make, or it can be passed on the command line -to -make.
-     For C++ compilation, the above example -makefile -(for basis.lib) contains examples for most of the required -elements.  Additional elements -will be discussed in the examples section or can be found in the -reference.  -The absolutely required variables for C++ are PROJECT, TYPE, SOURCE and -TARGETS. - -

     PROJECT is a variable that -provides the -name -of the project being compiled.  This should be a word that can -also -be used as a directory name and partial component of filenames.  -Thus, -spaces and other unusual punctuation characters are discouraged.  -All of the project's temporary directories will be created based on -this -variable.  This project name should be unique across a full build; -otherwise files generated by compiling identical project names will be -jumbled together. -

-

     TYPE is a variable that describes -the kind -of project that is being compiled.  This is necessary because it -controls -some aspects of the compilation, such as where the compilation products -are -generated.  All files generated by compilation are stored in the -repository -directory (by default, either "~/hoople" in Linux or "l:\" in -win32).  There are three TYPEs supported so far:

-
    - -
  • library: indicates that the project will primarily be -creating -static -or -dynamic libraries.
    • - -
  • application: indicates that the project will create -executables.
    • - -
  • test: indicates that the project constructs test -programs.
    • - -
-     Projects of the "library" type will -be given -an include directory named after the project, such as -"~/hoople/include/basis". - The include directory is created as a copy of the headers in the -project's -directory .  Library projects will also have their final products -copied -to the lib or dll subdirectories of the build directory being created.
-     Projects that are of type "application" will -have their executables -copied to the executable directory in the repository (such as -"~/hoople/exe").
-     The "test" type of project -will be promoted to a subdirectory named after the PROJECT that resides -under the test hierarchy in the repository (such as -"~/hoople/tests/turbodog"). - -

     SOURCE is a list of files that -are to be -compiled -in order to create the final products of the project.  These can -be -C++ source files (*.cpp), MS-Win32 resource files (*.rc) and other -types -of source files.  The list of objects to create will be determined -by transforming the list of SOURCE files (such as by turning a file -called -"fud.cpp" into an object called "fud.obj"). -

-

     TARGETS is a list of the products -that are -to be created by compilation and linking.  The suffix of a target -is a well established extension, such as ".lib", ".exe" -or ".dll" for MS-Win32 compilation products. -

-

Variable Assignment Policies

-     -The assignment of variable values is mostly straightforward, but it -might -be valuable to provide a refresher.  In GNU make, a variable -(a.k.a. -macro) can be assigned using the following syntax: - -
    - FRED = a b c -
-This sets the variable named FRED to the value of "a -b c".  The variable is referred to as $(FRED) when it is being -used, -although its name is just FRED.
-     This syntax is fine when the variable is to be -defined only once.  -In many cases though, a variable is already defined and needs to be -added -to instead of redefined.  Using the standard equals (=) operator -would -wipe out the previous definition, so a special assignment -is provided: - -
    - FRED += d e f -
-This is quite similar to the C syntax on integers.  It -means that -FRED will be given a value equal to its old value plus the new -contents.  -In our example, FRED would be equal to "a b c d e f".  Note that -one cannot say:
-
-          FRED = $(FRED) d e f -      (BAD!)
-
-This is not allowed in GNU make because it includes a macro's own value -in its definition.  This causes a badly formed recursive -definition -of the variable; a variable dereferencing operation (such -as $(FRED)) causes the variable's current value to -be resolved, which in turn dereferences any other variables in the -definition. - Thus, the reference to $(FRED) causes infinite recursion when -included -in the definition of FRED.
-
-     In the case of variables that must -be defined by the user's makefile, the standard assignment operator -(via the = character) can -be used.  This includes the PROJECT, TYPE, SOURCE, and TARGETS -variables.  -Also, any other variables that are set only by the user's makefile can -use simple assignment.  This category includes LOCAL_LIBS_USED, -LIBS_USED and others of similar nature.
-     But several variables are defined partially -by clam, then added to within the user's makefile, and then possibly -extended -after the user's makefile is processed (by the clam rules file).  -These variables cannot use -standard assignment and must instead use the incremental assignment -(+=) -operator.  Variables included in this category are DEFINITIONS, -LOAD_FLAG_PREFIX, -CLEANUPS, and many others. -
-     If you are unsure about the type of variable -you are defining, then the incremental assignment (+=) operator is -preferred -to avoid trashing the variable's previous values.
-     -Note that when variables are "exported", then any make in a subshell -will -inherit the parent shell's value.  This can induce some weird -behavior -for variables that are incrementally constructed with the += -operator.  -If this seems to be happening, try using the simple assignment operator -for -that variable in the sub-makefile, if this is allowed.  In general -though, -variables are not exported unless they MUST be seen by shell scripts -and -this does not occur overly frequently. - -

Optional Variables

-     There are several miscellaneous -variables that -are useful, either within one's makefiles or when passed to GNU make on -the command -line.  These are described below. - -

     LOCAL_LIBS_USED is a list of -library names -that are to be linked in with the library or executable being -created.  -These are specially formatted names; they are just the prefix part of -the -full library name.  For example, if you're building a release -executable -and want to link in a data structures library "i_adt.lib" (win32) or -"libi_adt.a" (Linux), you can specify: -
-        LOCAL_LIBS_USED = i_adt -
-The appropriate prefix and suffix will be attached. -

-

     EXTRA_COPIES is a list of files -that should be copied to a project's output folder when it is done -being compiled.  These should be files that are not already -copied as the main products, such as extra data or configuration files -that belong with an application. -

-

     EXTRA_VERSIONS is a list of -version files -that -also need to be updated to the main build version during a -compilation.  -These are usually needed if a project compiles several executable -files, -and each one performs version checking.  (By default, any project -containing a file called "version.ini" will get a version stamp from -the -main build version.) -

-

Writing Your Own Rules

-     One might need to write new rules -for -processing -file types that are not directly supported by clam.  There are a -number -of features provided for writing rules, but there are also some -requirements -placed on the rules. -
-     All rules in makefiles need to be prefaced -with one of the provided "launcher" macros.  These are used to -ensure -that the rules can be properly executed on different platforms; -Windoze95 -was especially hard to implement for until these macros were developed -(due to what appear to be basic defects in the command line -support).  -All preaching aside, here are the macros: - -
    - -
  • HIDER: Executes a command but hides the -invocation.  Any -output is -still sent to standard out.  If a verbose -build is being done, then all of the invocations become visible again.
    • - -
  • HIDESH: Executes a shell script but hides the -invocation. - Similar to HIDER but supports scripts specifically.
    -
    • - -
-Here are some examples of using the macros properly.  -Note that -the -command itself must be contained in single quotes:
-
-$(HIDER) $(MIDL) crumpet_server.idl
- -
MIDL is also a provided macro; it executes the -Microsoft -IDL compiler.
-$(HIDESH) $(CLAM_DIR)/postconditions.sh
- -
This runs a shell script that handles the end -portion of a -make.
-

-Conclusion

-     This tutorial is intended to raise -awareness -of -basic  usage.  Hopefully the reader will now be able to -create -simple makefiles that use .  For more aggressive compilation -requirements, -the reference section may be needed; it describes every variable and -rule -used in the  system.  However, it is most likely the case -that -your unsupported compilation needs will also be required by others in -the -future, and it is hoped that you will contribute them to the -main-line  support.  Currently, the appropriate way to do -this is just -to -send the makefile code to the library -administrator, who will include them -in the next version of . - -
-

-

-
-
- -

CLAM Reference

-
-

-Language Independent Variables

-     The language independent variables -are stored -in the file "$/variables.def".  They define the overall structure -of a make and can usually be overridden to customize how the make is -performed. - -

BUILD_BEFORE

-     This is a list of projects that need -to be -created -before this project can be created.  The items in the list are -interpreted -as directories that contain a makefile to be run.  For example, if -an item in BUILD_BEFORE is listed as ‘fred’, then the target -"fred.make" -will be executed.  That target changes to the directory 'fred' -before -running the makefile there.  The project in the specified -directory -is created using make if needed (as determined by that directory's -Makefile).  -The projects in BUILD_BEFORE are made immediately after the -FIRST_TARGETS -are made. - -

ACTUAL_TARGETS, ACTUAL_FIRST_TARGETS, ACTUAL_LAST_TARGETS

-     See below for TARGETS, FIRST_TARGETS and -LAST_TARGETS.
- -

BUILD_AFTER

-     A list of directory names that -should be -recursed -into after this project finishes.  Each listed directory will have -make -started on any makefile found.
- -

BUILD_BEFORE
-

-     A list of directory names that -should be -recursed into before this project -starts.  Each directory listed will have make started on any -makefile found.
- -

MAKEFILE_NAME

-     A variable that specifies the name -of the -makefile -for all sub-makes.  It works with BUILD_BEFORE and -BUILD_AFTER and allows the name of the makefile in a -subdirectory to be changed to something other than 'makefile'.  -This -supports different types of builds which are controlled by different -makefile -names. - -

PARAMETER_FILE

-     A file name that is -usually found at the root of the repository.  The name is -often "build.ini", but any name can be used as the parameter file. - This file is an extension of the variable set included in -$/variables.def -and can be used to provide compilation paramters without resorting to -the -command line.  This file is associated with a particular build -rather -than the  support, so different releases will have different build -parameter -files.  On systems supporting version information, the build's -version -number is stored here also.
- -

CATCHER

-     A sub-program launcher like HIDESH -but this will trap errors it sees and play the build error -CLAM_ERROR_SOUND.
- -

CLAM_BIN

-     This is a folder where the helper -binaries for  are located. The default for this is usually -CLAM_DIR/../bin.
- -

CLAM_DIR

-     This variable points at the location -where the  definitions and helper scripts are located.  The -default is -"~/yeti/clam", -but this can be overridden for local installations of .
- -

CLAM_ERROR_SOUND

-     This is a list of sound files -that should be played when a make stops with an error.  It serves -as -an audible warning that something bad happened.
- -

CLAM_FINISH_SOUND

-     This is a list of sound files -that should be played when the make has concluded -successfully.  It should play when the outer-most make -has seen all targets created as intended.
- -

CLAM_TMP

-     Specifies the location for temporary -files generated during a make.  The default value usually works -fine. - This directory will be created if it does not already exist.
- -

CLEANUPS

-     This is a list of files to be -removed by the -make -clean command.  They are possibly acquired from the TARGETS -defined -in the user's Makefile, or by language dependent rules for -cleaning.  -Additional files can be added to this list by the user's makefile also. - -

DIRTY_FILE

-     This variable points at a file that -signifies -that some targets have been remade.  It is not used at the base -level -of clam, but language-specific versions might do something special if -targets -were remade (such as put them in a build repository). - -

FAILURE_FILE

-     This file is used as a flag that -indicates -when -a make has failed.  The particular file used depends on the -project -name for this makefile.  It is cleared at both the beginning and -end -of a make. - -

FIRST_TARGETS

-     The FIRST_TARGETS are made before -any -libraries -are created and before any executables are compiled.  There must -be -a rule for making every entry in this list, either through implicit -rules -or explicit ones provided by the user's makefile. - -

FLAG_FILES

-     This is a list of all the files -that are used for compilation flags.  They are whacked at the -beginning -and end of a make.
- -

HIDER

-     This macro is used throughout  -to hide the -commands that are being sent to the operating system.  It can be -disabled to allow a verbose make (see the NOISY macro). - -

HIDESH

-     Just like HIDER, but this macro is -specifically -for launching shell scripts.  Some versions of GNU make (like -Cygwin's) -have problems running scripts which don't arise when running executable -files. - Those problems led to the creation of the HIDESH macro for those -specific -cases.  This is not an issue for Unix systems. - -

 LAST_TARGETS

-     The LAST_TARGETS are made after all -of the -other -standard targets are made.  Their must be a rule for making every -entry in this list, either through implicit rules or explicit ones -provided -by the user's makefile. - -

NOISY

-     This variable can be used to cause a -verbose -make.  -If the variable is non-empty, then all commands will be echoed to -standard -output.  Otherwise, the default is to hide the commands that are -issued -and just show the output of running those commands. - -

OP_SYSTEM

-     This is a flag that defines the -operating -system -name.  This flag is sometimes used to choose the appropriate tools -per platform or to conditionally compile code for system -dependent interfaces.  The available possibilities so far are -UNIX, -OS2, SYSV (System V Unix), DOS, and WIN32.  Only UNIX and WIN32 -are -currently very functional. - -

 OTHER_CLEANS

-     These are targets to execute before -performing -the main clean up during "make clean".  These might be targets -that -contain shell commands to execute as part of clean up or they could -contain -the "clean_subdirs" command (defined below). - -

PROJECT

-     This is a variable that provides the -name of -the -project being compiled.  This should be a word that can also be -used -as a directory name and as a partial component of filenames.  -Thus, spaces -and other unusual punctuation characters are discouraged.  All of -the project's temporary directories will be created based on this -variable. - -

FEISTY_MEOW_DIR

-     Specifies the root directory -for compilation or other  building activities.   The -repository -is also where source code and final products of compilation reside, -unless -the default is over-ridden (see TARGETS_DIR).
- -

SH & SHELL

-     These variables both point at a -shell program -that is -used for starting commands.  SHELL is defined by GNU make, whereas -SH is defined by . - -

SUB_FLAG_FILES

-     This is a list of the compilation -flag files -which -should be destroyed only at the end of a make.  They are used for -communication -with submakefiles--makefiles that were invoked by "this" makefile.
- -

SUBMAKE_FLAG

-     This points to a file whose presence -indicates -that -a "submake" performed some actions.  The flag can be interpreted -by -some language-specific versions of  as a reason to set a flag -using -the -DIRTY_FILE.
- -

TARGETS

-     These are the products to be created -by .  -Each item listed in TARGETS should have a rule that knows how to create -that type of file.  The language independent system provides very -few suffix based rules.  TARGETS is filled in by the user in -their  file, but it is not used directly by the  -system.  -Instead, -a generated variable called ACTUAL_TARGETS is used.
- -

TARGETS_DIR

-     This folder is where all generated -files are -to -be stored.  It is usually identical to FEISTY_MEOW_DIR but can be -overridden -when the targets should be stored elsewhere.
- -

Version components: major, minor, revision, build
-

-     These four variables specify the -version of -this -particular build.  They are usually stored in the -PARAMETER_FILE. - The major and minor versions are the traditional 2.3, 4.0, etc -style -of release numbers.  The revision number is often used to sequence -the -builds of that particular release, such that build 3.5.127 is the 127th -build -of the 3.5 release.
-     A version-tagged file (such as an executable or -dynamic -library) with any one of the major, minor or revision numbers differing -from -an installed build is incompatible with the installed build.  An -executable -file or dynamic library will not be allowed to load other dynamic -libraries -where these numbers differ.
-     The last version component is misleadingly called -"build"; -this number specifies the service pack level for a file.  Files -whose -versions only differ in the last "build" component are intended to be -compatible -with each other.  The understanding is that if only that number -differs, -then the external interface to the file has not changed, although the -interior -implementation may have.
- -

Language Independent -Rules

-     The file "$/rules.def" uses the -composite -macros -defined in "$/variables.def" together with a set of make rules to -perform -actions during compilation.  The rules file should be included in -the user's Makefile after the compilation variables have been -initialized -for the project being compiled.  The user's own targets should be -placed after the directive that includes "$/rules.def". - -

%.halt

-     These targets cause  to exit, -usually to -avoid -something that it considers catastrophic.  An example of this -would -be when  finds an inappropriate entry in the list of objects to -create; -allowing a "make clean" on this makefile will delete files that are -probably -not intended.  Hence, when  finds this kind of usage, it will -stop the make and issue a complaint. - -

%.make

-     Used to compile a makefile in a -subdirectory -named -"%".  This rule is employed by the BUILD_BEFORE macro, but can be -used in the user's makefile targets also. - -

Language Independent -Targets

-    The following targets are defined by -"$/rules.def". - -

all

-     This is a standard target that is -executed -when -no particular target is specified at the make command line.  It is -an umbrella target that invokes all of the other targets required to -perform -a make.  The order in which the major targets are created is: - -
    - -
  1. FIRST_TARGETS
    2. - -
  2. TARGETS
    3. - -
  3. LAST_TARGETS
    4. - -
-

-clean

-     This causes all of the files in -CLEANUPS to be -removed and also executes all of the targets in OTHER_CLEANS.  The -language dependent system can override some of this behavior or it can -just add more files to the list of CLEANUPS. - -

clean_subdirs

-     This is similar to "make_subdirs" in -that it -descends -into the subdirectories in no particular order, but it runs "make -clean" -in each of them.  This allows a directory hierarchy of projects to -be cleaned with one command. - -

finish

-     The "finish" target represents the -completion -of a make, whether successful or not.  It reports the time and -date -(and logs them). - -

rm_links

-     This target causes all link files in -the -current -directory to be deleted.  This is only applicable on a Unix -operating -system. - -

make_subdirs

-     This target allows a makefile to -specify that -all of the subdirectories under the current directory should be scanned -for makefiles and that those makefiles should be executed.  If a -makefile -does not exist, it is skipped.  Note that the subdirectories are -descended -into in no particular order; the order depends on how the operating -system -decides to list the directories.  If the order of make is -important, -use BUILD_BEFORE instead. - -

start

-     The "start" target represents the -beginning of -the make.  It reports the time and date (and logs them). - -

Language Independent -Files

-

$(PARAMETER_FILE)

-     This is a special -file that has at least two purposes in .  It is the source of -the -version number that will be stamped on all the appropriate DLLs and -EXEs -created during a build.  It is also a place where build-wide -compilation -directives can be included so that they do not have to be passed on the -command -line.  For C++ compilation, this is usually an INI file -stored in the -FEISTY_MEOW_DIR under the build folder.  -Here is a sample parameter file: - -
#\
- [version]
- major=14
- minor=3
- revision=140
- build=0 -

DEBUG=t
- OPTIMIZE=t
-

-
-Note the bizarre comment at the top of the makefile; this is -used to -hide -the "[version]" section marker.  The comment is required because -the -build parameter file is pulled directly into the makefile code to set -the -variables after the version stamp.  Without a comment in front of -the section, a syntax error would result.  The "[version]" section -marker is required because this file is also sometimes treated as a -win32 INI file -in order to read the version stamp.
-     The build version is stored in the first four -entries.  Our interpretation of the stamp is standard for "major" -and "minor".  We treat the "revision" as a build revision number; -within a release, there will be numerous revisions--one for each new -build -that is performed.  We then treat the "build" entry as a patch -level -within that particular build.  When we perform our version -checking, -only the first three entries are compared; the patch level in "build" -is -considered irrelevant. -
-     This example also specifies that the build -should be a debug style (rather than release) build and that it should -be optimizer.  We can also see that -the flags for bounds checker instrumentation and true time -analysis support are commented out.
- -

badness_catcher.sh

-     Runs the command line passed -in as a sub-shell and looks for error conditions.  If an error -occurred, -the build is stopped and the CLAM_ERROR_SOUND is played.
- -

datestamp.sh

-     Echoes the time and date.  This -is a -separate -file to make the cross-platform difference less annoying.
- -

exit_make.sh

-     Causes the make to stop dead in its -tracks. - -

postconditions.sh

-     Invoked at the end of the -language-invariant -portion of a make.
- -

preconditions.sh

-     Invoked at the beginning of the -language-invariant portion of a make.
- - -

starter.sh

-     This shell script executes a command -that is -passed -to it as its parameters and logs error conditions to standard -output.  -It's used by the CATCHER macro. - - -

-

-

-C++ Specific Variables

-     These variables are used throughout -the C++ -compilation -support.  They are defined in "$/cpp/variables.def". - - -

BASE_CPU

-     Allows specification of the -processor that the -build is targeted for.  This is needed when special actions must -be -taken for different processor types.  Valid values currently -include -m68k (for Motorola 68000 series), m68340 (specifically the 68340), -x86 (intel 386 and upwards), and ppc860 (the PowerPC 860). - -

BUILD_LIST_FILE

-     The list of files that must -be rebuilt.  This is only used with compilers that support -compilation -of multiple source files with one invocation of the compiler (currently -only -MS-Visual C++).
- -

BUILD_WHACK_FILE

-     A list of object files that must be -destroyed -if -the make fails.  This is only relevant in the same situations as -BUILD_LIST_FILE.
- -

COMPILER

-     This variable chooses the specific -flags -needed -for the compiler.  Not all operating system choices above are -suitable -with the COMPILER choices, but generally it is fairly obvious which are -supported.  The current possibilities include BORLAND_DOS, -BORLAND_OS2, -UNIX (default cc), GNU_OS2, GNU_LINUX, OBJECT_CENTER (Saber compiler), -SUN_UNIX, -VISUAL_CPP, and DIAB3. - -

COMPILER_FLAGS

-     This is the list of flags passed to -the -preprocessor -and compiler. It is composed of the SYSTEM, the DEFINITIONS, the -SEARCH_DIRS, -and any user-included options. If flags that don't fit one of the -categories -are needed, they can be added here. - -

CONSOLE_MODE

-     This causes the program -to be generated as a console application.  This is relevant in -systems -(such as win32) where programs have a split personality depending on -whether -they are to have graphical user interfaces or just console interfaces. - -

DEBUG_FLAGS

-     These are flags used for generating -specialized -versions of object files, such as ones that include debugging code -(e.g., -for gdb) or ones that add code for profiling (e.g., gprof). Possible -values -in the Sun CenterLine Compiler environment are -g for debugging code -and --pg for profiling. - -

DEFINITIONS

-     This is a list of compiler flags -that define -the -value of C or C++ macros. These usually have the format of -‘-D<flag>’, -but in this particular variable only the <flag> itself should be -listed -(because the compiler option characters ‘-D’ are added automatically). - -

DEPENDENCY_ADDITIONS

-     This is a list of extra flags that -gets passed -to the auto-dependency tool.  The list can vary for each compiler. - -

DEPS_FILE

-     This file is where the -auto-dependency -information -is stored.  The "makedep" program is used to generate -auto-dependency -information for the files listed in SOURCE.  During a build, the -DEPS_FILE -is pulled into the actual code of the makefile; this causes the -dependencies -to be automatically included so that they can dictate the files that -need -to be rebuilt. - - -

EXTRA_VERSIONS

-     This is a list of version files that -also need -to be updated to the main build version during a compilation.  -These -are usually needed if a project compiles several executable files, and -each one performs version checking.  By default, any project -containing -a file called "version.ini" will get a version stamp from the main -build -version. - -

LIBRARIAN_FLAGS

-     This is a list of flags that are -passed to the -library creation tool.  Sometimes this must be overridden for a -particular -compiler. - -

LIBS_USED

-     These are code libraries that the -executables -depend upon.  They are searched for in any of the directories -listed -in the LIBRARY_SEARCH_PATH. - -

LOAD_FLAG_PREFIX & LOAD_FLAG_SUFFIX

-     These tell the linker and loader how -to deal -with -the files and where to locate library components. The prefix is listed -on the compilation command line before the object files are listed, and -the suffix after. The prefix should contain information such as the -directories -to be searched for code libraries (although they should be added to -LIBRARY_SEARCH_PATH).  -In the suffix definition, actual library loading statements (like --lmath) -can be included (although they should be listed in a different form in -LIBS_USED or LOCAL_LIBS_USED). - -

LOCAL_LIBS_USED

-     The names in this list actually -cause the -OBJECTS -to be recompiled when the libraries listed have changed.  To -accomplish -this, these libraries MUST be located in the STATIC_LIBRARY_DIR rather -than -at some arbitrary place on the LIBRARY_SEARCH_PATH.  These -libraries -also must follow the special naming convention followed by ; if -"basis" -is an entry in this list, then a library called "basis.lib" will be -sought -during the build. - -

NO_COMPILE

-     Specifies that no compilation -should be performed.  Nothing in the SOURCE or TARGETS macros will -be -built.
- -

NO_DEPS

-     This is an exclusion flag.  If -it is -defined, -then no auto-dependency files will be generated.  This is useful -if -you're missing the makedep tool and trying to compile it.
- -

OBJECTS

-     The OBJECTS are all those files that -need to -be -created during compilation.  Usually this list is filled based on -the files in SOURCE. - -

OPTIMIZE

-     Causes the make to create optimized -code.  -The default optimization is for speed. - -

REBUILD

-     If the REBUILD variable is -non-empty, then all -files listed in the SOURCE variable are touched.  This should -cause -all of those files to be rebuilt during the compilation.  -Occasionally -GNU make will complain that a file is newer than the current time, but -this does not usually cause any problems. - -

SOURCE

-     The SOURCE variable is a list of -files that -are -to be compiled in order to create the final products of the -project.  -These can be C++ source files (*.cpp), Win32 resource files (*.rc) -and -other types of source files.  The list of objects to create will -be -determined by transforming the list of SOURCE files (such as by turning -a file called "fud.cpp" into an object called "fud.obj").  More -file -types will be added as they are needed. - -

STATIC

-     Causes the make to create statically -linked -targets.  -Executables or dynamic libraries will not link in any compiler supplied -dynamic libraries, nor will they require them during run-time. - -

TYPE

-     This is a variable that describes -the kind of -project that is being compiled.  Knowing the type of project is -necessary -because it controls some elements of the compilation and also of the -final -promotion of the compiled products.  There are three TYPEs -supported -so far: - -
    - -
  • library: indicates that the project will be primarily -creating -static -or -dynamic libraries.
    • - -
  • application: indicates that the project will create -executables.
    • - -
  • test: indicates that the project constructs test -programs.
    • - -
-Projects of the "library" type will follow the special  -rules for -their include directory (which is created as a copy of headers in the -library -directory).  Library projects will also have their final products -copied to the lib or dll subdirectories of the build directory being -created.  -Projects that are "application"s will have their executables copied to -the executable directory in the build.  And "test" projects will -be -promoted to a subdirectory named after the PROJECT that resides under -the -test hierarchy in the build. - -

C++ Directory Structure -Variables

-

BASE_OUTPUT_PATH

-     This is the parent directory -for object files generated for the specified type of CPU and the style -of -build (e.g. debug or release builds).
- -

CPU_BUILD_DIR

-     This variable can be used to -distinguish -directory -names used for output.  It includes the cpu name and the type of -build. - -

DYNAMIC_LIBRARY_DIR

-     The directory where dynamic -libraries will be -stored after creation.
- -

EXECUTABLE_DIR

-     The directory where executable files -will be -stored after creation.
- -

FINAL_DIR

-     This is the name of the directory -where the -finished -compilation products are stored, currently only import libraries for -dynamic libraries.  -It is usually a directory under the OUTPUT_PATH named "final". - -

HEADER_SEARCH_PATH

-     This is a list of directories that -will be -searched -for C++ header files (files ending in ‘.h’). - -

HOOPLE_HEADERS

-     The two standard places to look for -headers -(the repository and the third party directory) are listed in this -variable. - -

HOOPLE_LIBRARIES

-     This is where our libraries are -located.  It is usually a subdirectory called "lib" under the -repository -directory. - -

LIBRARY_SEARCH_PATH

-     This is a list of directories that -will be -searched -for C++ library archives (files ending in ".a" or ".lib"). - -

LOCAL_HEADERS

-     This variable provides a way to -include -headers -prior to the default locations in the search path.  For example, -if -you are compiling locally and have some headers that are not present in -the build you are using, then you can specify where they are in this -variable. - -

LOCAL_LIBRARIES

-     This variable allows other library -directories -to be added prior to the default search locations.  This enables -substitute -static or import libraries to be used instead of the standard ones -present -in the build. - -

STATIC_LIBRARY_DIR

-     This is the location where code -libraries are -to be copied during promotion and where they are to be searched for -when -listed in LOCAL_LIBS_USED.  Under Unix, these libraries have a -‘.a’ -suffix and are created with the "ar" program.  Under Win32, -these -libraries have a ‘.lib’ suffix and are created with "link". - -

OBJECT_DIR

-     This is where object files will be -stored -during -compilation for the target type being produced. - -

OUTPUT_DIRECTORY_LIST

-     This is a list of directories that -need to be -created under the OUTPUT_PATH.  It contains the "final" directory -where all finished products are stored, as well as all the intermediate -directories for objects. - -

OUTPUT_PATH

-     This is the temporary file storage -area.  -Any files that are created during the compilation process will be -stored -under here in a subdirectory named after the PROJECT. - -

OUTPUT_ROOT

-     This specifies the root portion of -the -OUTPUT_PATH.  -It lets a PC build use drive letters for the root, while a Unix build -can -specify a directory hierarchy. - -

SEARCH_DIRS

-     This is a list of directories that -will be -searched -for both C++ header files and for C++ code libraries.  The items -placed -on SEARCH_DIRS will be added to both the LIBRARY_SEARCH_PATH and the -HEADER_SEARCH_PATH.  -The reasoning behind this variable is lost in antiquity. - -

TESTS_DIR
-

-     The directory where test programs -will be -stored after creation.
- -

THIRD_PARTY_DIR

-     Third party components are sometimes -used in -the -creation of products.  The directory is expected to have a -structure -containing "include" and "lib" subdirectories where headers and -libraries -are stored. - -

Compiler Dependent Flags

-

-CC

-     This is the name of the C++ compiler -executable. - -

COMPILER_HEADER_DIR

-     This is where the compiler's header -(or -include) -root directory is located.  It is usually based on the root -directory. - -

COMPILER_LIBRARY_DIR

-     This is where the code libraries for -the -compiler -are located.  It is usually based on the root directory. - -

COMPILER_ROOT_DIR

-     This should automatically be set to -the -appropriate -local directory where the C++ compiler is located. - -

CREATE_LIBRARY_FLAG

-     This flag, if required, specifies -the text -that -must precede the name of a library to create.  It is passed to the -library creation tool. - -

DEF_FILE

-     This flag only applies to Win32 -programs.  -It specifies the name of a DEF file for all of the products created in -the project. - -

LIB_PREFIX & LIB_SUFFIX

-     The portions of a library's name -dictated by the operating system.  For example, on Unix the prefix -is "lib" -and the suffix is ".a", leading to library names like "libbasis.a" for -the -basis library.  On win32, the prefix is "" and the suffix is -".lib", leading -to library names like "basis.lib".
- -

LIBRARY_NAME_FLAG

-     This flag contains the text that -specifies a -library -that will be included in a link.  It is often "-l". - -

LIBRARY_PATH_FLAG

-     This flag provides the text needed -to add -another -library search path.  Multiple occurrences of this flag followed -by -a directory name are allowed by most compilers. - -

LIBRARY_TOOL

-     This is the name of the program -responsible -for -creating libraries. - -

LINK_TOOL

-     This is the name of the program that -links.  -This is sometimes the same as the compiler (CC) and sometimes the same -as the librarian (LIBRARY_TOOL). - -

LINKER_OPTION_SEPARATOR

-     In some compilers, linker options -need to be -separated -from compiler options that occur on the same command line.  This -flag -serves that purpose. - -

LINKER_OUTPUT_FLAG

-     This flag is sometimes required by a -linker -for -specifying the name of the library or executable that it is creating. - -

OBJECT_NAME_FLAG

-     This flag is used to specify the -name of an -object -file being created.  It is passed to the compiler to override -whatever -default name would be used. - -

Microsoft-Visual C++ Only
-

-

USE_MFC

-     This flag only applies to Visual C++ -and -indicates -that MFC is to be used in creating this project.  This is usually -the case for GUI applications. - -

VC_ROOT

-     This is an override that allows the -compiler -root -directory to be customized without changing the  code.  If -VC_ROOT -is set (either in a makefile or as an external variable), then it will -be used in place of the COMPILER_ROOT_DIR.  The best way to use -this -override is as an external environment variable; this allows makefiles -to remain the same despite your local configuration of the compiler. -
-     Note that this variable should use -forward-slashes, -where DOS/Win32 would use backslashes.  Also, if you have -installed -Visual C++ in a directory path containing space characters, then please -use the 8.3 notation for the directories containing the spaces; this -allows -the name to be passed around successfully.  For example... - -
- - - - - - - - - - - - - - - - - - - - -
-
If Visual C++ Is Installed In
- 		-
Then VC_ROOT Should Be
-
-
c:\devstudio\vc
- 		-
c:/devstudio/vc
-
-
c:\program files\devstudio\vc
- 		-
c:/progra~1/devstudio/vc
-
-
-

VCS_ROOT

-     Similarly to the VC_ROOT, this -variable points -at the root of the C# support for Visual Studio.Net.
- -

FRAMEWORK_DIR

-     This variable specifies the location -of the -.Net framework directory.  On MS-Windows XP, the default should be -fine.  For MS-Windows 2000 or other Win32 OSes, the windows -directory -should be "winnt" instead.  If the operating system is configured -in a non-default way, the framework directory can be specified in an -environment variable.
- -

VCPP_USE_BASE

-     Specifies that standard Win32 -libraries should -be linked in.
- -

VCPP_USE_GUI

-     Specifies that the MFC libraries -should be -linked in. - -

VCPP_USE_OLE

-     Specifies that the COM / OLE -libraries should -be linked in. - -

VCPP_USE_RPC

-     Specifies that the MS-RPC libraries -should be -linked in.
- -

VCPP_USE_SOCK

-     Specifies that the MS-WinSock -libraries should -be linked in.
- -

C++ Specific Rules

-     These types of targets have one -thing in -common; -if any of the items that a target depends on in SOURCE or -LOCAL_LIBS_USED -or included files or whatever have changed since the last time the -target -was created, then it is recompiled. - -

%.bad

-     Causes the make to die.  This -is added when an incorrect file type is spotted in a list of targets.
- -

%.dll

-     These create dynamically linked -libraries from -the SOURCE. - -

%.elf

-     Creates elf-formatted binaries for -use with a -firmware build (a specialized RTOS is the only one currently supported).
- -

%.exe

-     This creates an executable program -using all -of -the objects and libraries specified.  It is therefore important in -a  makefile to only have executables that depend on the same group -of object files.  The hidden agenda in the "exe" type of target is -that a file ending in ".cpp" must exist; this is taken as the root of -the -executable.  It should usually contain the main() function (or its -equivalent). - -

%.lib

-     This creates static libraries from -the files -listed -in OBJECTS. - -

%.nil

-     A blank target for test compiles.
- -

%.obj

-     These create object files from C++ -source -files -(files ending in .c or .cpp). - -

%.res

-     These create compiled resource files -from RC -files -in the SOURCE list. - -

C++ Specific Targets

-

-check_requirements

-     This target ensures that certain -characteristics -of the makefile are present.  It complains and aborts the make if -they are missing. - -

post_compilation

-     This target finalizes the -compilation by -running -the postconditions script.  If PROMOTE is true, then the final -products -are copied into the repository. - -

pre_compilation

-     This target executes the -preconditions script -to set up the compilation's output directories. - -

rebuild

-     This target performs the actions of -rebuilding.  -This mainly involves touching all of the files in SOURCE before the -compilation -has really started. - -

C++ Specific Files

- -

postconditions.sh

-     After a compilation has succeeded, -the -postconditions -script performs the final actions required.  The nature of these -actions -depends on the type of project being made.  For a library project, -the script copies the headers to the project's include directory and -copies -libraries to the appropriate locations.  For application and test -program targets, the script copies the final products to the -appropriate -repository directory. - -

preconditions.sh

-     Before any targets are compiled, the -preconditions -script ensures that the appropriate output directories exist for the -project.  -The script also calls the version utilities to update the project's -version -file and to create any required resource files.
- -

rebuild_oldies.sh

-     Used for compilers that support -multiple code -files -in one invocation.  This is launched to compile a batch of sources -and -catch any errors.
- -
-
-

CLAM Example Makefiles

-
-     These examples show some common -patterns for -how  is used.  The makefiles below are actually used in real -software -projects. - -

Library-Only Makefile

-This example creates a dynamic library. - -
    - include cpp/variables.def - -

    PROJECT = mechanisms
    - TYPE = library
    - SOURCE = delayer.cpp eventmgr.cpp event_po.cpp heartbea.cpp -instance.cpp -\
    -   libmain.cpp monitor.cpp semaphor.cpp state_ma.cpp -timer.cpp -time_sta.cpp
    - TARGETS = mechanisms.dll
    - LOCAL_LIBS_USED = basis
    - DEFINITIONS += BUILD_MECHANISMS USE_HOOPLE_DLLS

    - -

    include cpp/rules.def

    - -
-The dynamic library created here is mechanisms.dll.  The -basis -library is linked -in also.  The file "roller.cpp" will also be copied to the build -directory's -include path, presumably since it is a template code file. - -

Library Plus Executable Makefile

-This example shows the basis makefile with a couple of test -programs -also -being generated. - -
    - include cpp/variables.def - -

    PROJECT = basis
    - TYPE = library
    - SOURCE = chaos.cpp checkup.cpp guards.cpp \
    -   istring.cpp itime.cpp logger.cpp matrix.cpp -portable.cpp \
    -   realtime.cpp textdump.cpp timezone.cpp utility.cpp \
    -   version_checker.cpp version_record.cpp
    - TARGETS = basis.lib t_string.exe t_alloc.exe

    - -

    include cpp/rules.def

    - -
-Note that the executables -"t_string.exe" and "t_alloc.exe" require files called "t_string.cpp" -and -"t_alloc.cpp" to exist.  These files are expected to contain the -"main()" -or "WinMain()" functions (or the MFC application object).  All of -the -files in the SOURCE variable will be included in each final executable. - -

Executable-Only Makefile

-This example is produces several test programs that exercise -the -associated -library. - -
    - include cpp/variables.def - -

    PROJECT = t_basis
    - TYPE = test
    - SOURCE = instance.cpp t_basis.rc
    - TARGETS = t_alloc.exe t_chaos.exe t_checku.exe t_dattim.exe \ -
    -   t_matrix.exe t_sequen.exe t_sorts.exe t_string.exe \
    -   t_texdmp.exe
    - LOCAL_LIBS_USED = basis

    - -

    include cpp/rules.def

    - -
-The programs "t_alloc.exe" and so on will require C++ files -with the -same -prefix (t_alloc.cpp) to contain the main program (as in the previous -example).  -The items in the SOURCE list will be included in each executable, and -the -basis library will be linked in. - -

CLAM Hints

-     This section -is devoted to untangling snags that have been encountered in the -past.  -Hopefully problems you encounter will be discussed here.  Please -contribute -any new problems found to the library -administrator. - -

Problem:

-     A message like: - -
    - -
      - make: *** No rule to make target -`o:/x86_w32_rel/project/final/myproj.dll', -needed by `all'.  Stop. -
    - -
-is displayed during a make. - -

Solution:

-     The most frequent reason for -receiving a -message -similar to the above is that there is a file listed in SOURCE that -either -does not exist or that is capitalized differently from how it is -listed.  -Check that all the files in SOURCE are in the makefile's directory and -that the exact spelling of those files (including their case) is -correct. -
-     Another potential cause of this problem is -if a file is included in the SOURCE that  does not -recognize.  -The standard compilable files are supported (*.cpp, *.c, *.rc), but it -is possible that a makefile must handle a non-standard extension (such -as *.idl).  Either the user's makefile must supply a rule for -processing -this type of file or the user must negotiate with the  -administrator -to get that type of target added to the  support. - -

Problem:

-      Clam is complaining about programs -not being -found -during a build. - -

Solution:

-     The most frequent cause of this -problem is a -directory -not being on your path.  The compilation tools bin (~/hoople/bin) -directory must be in -the PATH variable. -
-     Problems are occasionally seen when the PATH -contains directory names that have spaces in them.  Try using the -shorter 8.3 form of the directory name. -
-     An even more obscure situation sometimes -occurs: paths with networked drives seem to somehow hide paths with -local drives that -are listed later in the PATH variable.  The cause of this is -unknown, -although it was thought to be caused by NetWare at one point.  To -fix -the situation, move the local paths before the networked ones.
-
- -
-
-

Acknowledgements

-
-
Thanks to April Bly Monnen for the wonderful cover -art. - -

Thanks to Kevin Wika for some early help with makefiles. -

- - -
-
-
- - - diff --git a/docs/clam_manual/clam_root.html b/docs/clam_manual/clam_root.html deleted file mode 100644 index 89b9889b..00000000 --- a/docs/clam_manual/clam_root.html +++ /dev/null @@ -1,38 +0,0 @@ - - - - - - - CLAM Home Page - - - -
-

clam automagic maker

-
-
-

-Tutorial and Reference Manual -
-
-GNU Make -Manual -
-
-CLAM Source -
-
-CLAM C++ Support Source -
-
-CLAM C# Support Source -
-
You can download CLAM from the hoople -site.
-Please send any comments and contributions to the -Administrator -.
-
- - \ No newline at end of file diff --git a/docs/clam_manual/partial_cygwin_for_build.txt b/docs/clam_manual/partial_cygwin_for_build.txt deleted file mode 100644 index 0f33a59e..00000000 --- a/docs/clam_manual/partial_cygwin_for_build.txt +++ /dev/null @@ -1,32 +0,0 @@ - -install these groups: -base - default should be okay -devel - - add make -shells - default should be okay - -optional items: -admin - add shutdown -archive - add sharutils - add zip - add unzip -devel - add cvs -editors - add gvim - add vim - add emacs -interpreters - add perl -net - add openssh -text - add less -utils - add pcre (needed by less) - add cygutils (provides cal and other useful tools) - - - diff --git a/docs/feisty_meow_dox.config b/docs/feisty_meow_dox.config deleted file mode 100644 index 0a041967..00000000 --- a/docs/feisty_meow_dox.config +++ /dev/null @@ -1,1219 +0,0 @@ -# Doxyfile 1.5.0 - -# This file describes the settings to be used by the documentation system -# doxygen (www.doxygen.org) for a project -# -# All text after a hash (#) is considered a comment and will be ignored -# The format is: -# TAG = value [value, ...] -# For lists items can also be appended using: -# TAG += value [value, ...] -# Values that contain spaces should be placed between quotes (" ") - -#--------------------------------------------------------------------------- -# Project related configuration options -#--------------------------------------------------------------------------- - -# The PROJECT_NAME tag is a single word (or a sequence of words surrounded -# by quotes) that should identify the project. - -PROJECT_NAME = "feisty meow concerns codebase" - -# The PROJECT_NUMBER tag can be used to enter a project or revision number. -# This could be handy for archiving the generated documentation or -# if some version control system is used. - -PROJECT_NUMBER = 2.108 - -# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) -# base path where the generated documentation will be put. -# If a relative path is entered, it will be relative to the location -# where doxygen was started. If left blank the current directory will be used. - -OUTPUT_DIRECTORY = - -# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create -# 4096 sub-directories (in 2 levels) under the output directory of each output -# format and will distribute the generated files over these directories. -# Enabling this option can be useful when feeding doxygen a huge amount of -# source files, where putting all generated files in the same directory would -# otherwise cause performance problems for the file system. - -CREATE_SUBDIRS = NO - -# The OUTPUT_LANGUAGE tag is used to specify the language in which all -# documentation generated by doxygen is written. Doxygen will use this -# information to generate all constant output in the proper language. -# The default language is English, other supported languages are: -# Afrikaans, Arabic, Brazilian, Catalan, Chinese, Chinese-Traditional, -# Croatian, Czech, Danish, Dutch, Finnish, French, German, Greek, Hungarian, -# Italian, Japanese, Japanese-en (Japanese with English messages), Korean, -# Korean-en, Lithuanian, Norwegian, Polish, Portuguese, Romanian, Russian, -# Serbian, Slovak, Slovene, Spanish, Swedish, and Ukrainian. - -OUTPUT_LANGUAGE = English - -# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will -# include brief member descriptions after the members that are listed in -# the file and class documentation (similar to JavaDoc). -# Set to NO to disable this. - -BRIEF_MEMBER_DESC = YES - -# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend -# the brief description of a member or function before the detailed description. -# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the -# brief descriptions will be completely suppressed. - -REPEAT_BRIEF = YES - -# This tag implements a quasi-intelligent brief description abbreviator -# that is used to form the text in various listings. Each string -# in this list, if found as the leading text of the brief description, will be -# stripped from the text and the result after processing the whole list, is -# used as the annotated text. Otherwise, the brief description is used as-is. -# If left blank, the following values are used ("$name" is automatically -# replaced with the name of the entity): "The $name class" "The $name widget" -# "The $name file" "is" "provides" "specifies" "contains" -# "represents" "a" "an" "the" - -ABBREVIATE_BRIEF = - -# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then -# Doxygen will generate a detailed section even if there is only a brief -# description. - -ALWAYS_DETAILED_SEC = NO - -# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all -# inherited members of a class in the documentation of that class as if those -# members were ordinary class members. Constructors, destructors and assignment -# operators of the base classes will not be shown. - -INLINE_INHERITED_MEMB = NO - -# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full -# path before files name in the file list and in the header files. If set -# to NO the shortest path that makes the file name unique will be used. - -FULL_PATH_NAMES = YES - -# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag -# can be used to strip a user-defined part of the path. Stripping is -# only done if one of the specified strings matches the left-hand part of -# the path. The tag can be used to show relative paths in the file list. -# If left blank the directory from which doxygen is run is used as the -# path to strip. - -STRIP_FROM_PATH = - -# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of -# the path mentioned in the documentation of a class, which tells -# the reader which header file to include in order to use a class. -# If left blank only the name of the header file containing the class -# definition is used. Otherwise one should specify the include paths that -# are normally passed to the compiler using the -I flag. - -STRIP_FROM_INC_PATH = - -# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter -# (but less readable) file names. This can be useful is your file systems -# doesn't support long names like on DOS, Mac, or CD-ROM. - -SHORT_NAMES = NO - -# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen -# will interpret the first line (until the first dot) of a JavaDoc-style -# comment as the brief description. If set to NO, the JavaDoc -# comments will behave just like the Qt-style comments (thus requiring an -# explicit @brief command for a brief description. - -JAVADOC_AUTOBRIEF = NO - -# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen -# treat a multi-line C++ special comment block (i.e. a block of //! or /// -# comments) as a brief description. This used to be the default behaviour. -# The new default is to treat a multi-line C++ comment block as a detailed -# description. Set this tag to YES if you prefer the old behaviour instead. - -MULTILINE_CPP_IS_BRIEF = NO - -# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented -# member inherits the documentation from any documented member that it -# re-implements. - -INHERIT_DOCS = YES - -# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce -# a new page for each member. If set to NO, the documentation of a member will -# be part of the file/class/namespace that contains it. - -SEPARATE_MEMBER_PAGES = NO - -# The TAB_SIZE tag can be used to set the number of spaces in a tab. -# Doxygen uses this value to replace tabs by spaces in code fragments. - -TAB_SIZE = 2 - -# This tag can be used to specify a number of aliases that acts -# as commands in the documentation. An alias has the form "name=value". -# For example adding "sideeffect=\par Side Effects:\n" will allow you to -# put the command \sideeffect (or @sideeffect) in the documentation, which -# will result in a user-defined paragraph with heading "Side Effects:". -# You can put \n's in the value part of an alias to insert newlines. - -ALIASES = - -# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C -# sources only. Doxygen will then generate output that is more tailored for C. -# For instance, some of the names that are used will be different. The list -# of all members will be omitted, etc. - -OPTIMIZE_OUTPUT_FOR_C = NO - -# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java -# sources only. Doxygen will then generate output that is more tailored for Java. -# For instance, namespaces will be presented as packages, qualified scopes -# will look different, etc. - -OPTIMIZE_OUTPUT_JAVA = NO - -# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want to -# include (a tag file for) the STL sources as input, then you should -# set this tag to YES in order to let doxygen match functions declarations and -# definitions whose arguments contain STL classes (e.g. func(std::string); v.s. -# func(std::string) {}). This also make the inheritance and collaboration -# diagrams that involve STL classes more complete and accurate. - -BUILTIN_STL_SUPPORT = NO - -# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC -# tag is set to YES, then doxygen will reuse the documentation of the first -# member in the group (if any) for the other members of the group. By default -# all members of a group must be documented explicitly. - -DISTRIBUTE_GROUP_DOC = NO - -# Set the SUBGROUPING tag to YES (the default) to allow class member groups of -# the same type (for instance a group of public functions) to be put as a -# subgroup of that type (e.g. under the Public Functions section). Set it to -# NO to prevent subgrouping. Alternatively, this can be done per class using -# the \nosubgrouping command. - -SUBGROUPING = YES - -#--------------------------------------------------------------------------- -# Build related configuration options -#--------------------------------------------------------------------------- - -# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in -# documentation are documented, even if no documentation was available. -# Private class members and static file members will be hidden unless -# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES - -EXTRACT_ALL = YES - -# If the EXTRACT_PRIVATE tag is set to YES all private members of a class -# will be included in the documentation. - -EXTRACT_PRIVATE = NO - -# If the EXTRACT_STATIC tag is set to YES all static members of a file -# will be included in the documentation. - -EXTRACT_STATIC = NO - -# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) -# defined locally in source files will be included in the documentation. -# If set to NO only classes defined in header files are included. - -EXTRACT_LOCAL_CLASSES = NO - -# This flag is only useful for Objective-C code. When set to YES local -# methods, which are defined in the implementation section but not in -# the interface are included in the documentation. -# If set to NO (the default) only methods in the interface are included. - -EXTRACT_LOCAL_METHODS = NO - -# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all -# undocumented members of documented classes, files or namespaces. -# If set to NO (the default) these members will be included in the -# various overviews, but no documentation section is generated. -# This option has no effect if EXTRACT_ALL is enabled. - -HIDE_UNDOC_MEMBERS = NO - -# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all -# undocumented classes that are normally visible in the class hierarchy. -# If set to NO (the default) these classes will be included in the various -# overviews. This option has no effect if EXTRACT_ALL is enabled. - -HIDE_UNDOC_CLASSES = NO - -# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all -# friend (class|struct|union) declarations. -# If set to NO (the default) these declarations will be included in the -# documentation. - -HIDE_FRIEND_COMPOUNDS = NO - -# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any -# documentation blocks found inside the body of a function. -# If set to NO (the default) these blocks will be appended to the -# function's detailed documentation block. - -HIDE_IN_BODY_DOCS = NO - -# The INTERNAL_DOCS tag determines if documentation -# that is typed after a \internal command is included. If the tag is set -# to NO (the default) then the documentation will be excluded. -# Set it to YES to include the internal documentation. - -INTERNAL_DOCS = NO - -# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate -# file names in lower-case letters. If set to YES upper-case letters are also -# allowed. This is useful if you have classes or files whose names only differ -# in case and if your file system supports case sensitive file names. Windows -# and Mac users are advised to set this option to NO. - -CASE_SENSE_NAMES = YES - -# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen -# will show members with their full class and namespace scopes in the -# documentation. If set to YES the scope will be hidden. - -HIDE_SCOPE_NAMES = NO - -# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen -# will put a list of the files that are included by a file in the documentation -# of that file. - -SHOW_INCLUDE_FILES = YES - -# If the INLINE_INFO tag is set to YES (the default) then a tag [inline] -# is inserted in the documentation for inline members. - -INLINE_INFO = YES - -# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen -# will sort the (detailed) documentation of file and class members -# alphabetically by member name. If set to NO the members will appear in -# declaration order. - -SORT_MEMBER_DOCS = YES - -# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the -# brief documentation of file, namespace and class members alphabetically -# by member name. If set to NO (the default) the members will appear in -# declaration order. - -SORT_BRIEF_DOCS = NO - -# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be -# sorted by fully-qualified names, including namespaces. If set to -# NO (the default), the class list will be sorted only by class name, -# not including the namespace part. -# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. -# Note: This option applies only to the class list, not to the -# alphabetical list. - -SORT_BY_SCOPE_NAME = NO - -# The GENERATE_TODOLIST tag can be used to enable (YES) or -# disable (NO) the todo list. This list is created by putting \todo -# commands in the documentation. - -GENERATE_TODOLIST = YES - -# The GENERATE_TESTLIST tag can be used to enable (YES) or -# disable (NO) the test list. This list is created by putting \test -# commands in the documentation. - -GENERATE_TESTLIST = YES - -# The GENERATE_BUGLIST tag can be used to enable (YES) or -# disable (NO) the bug list. This list is created by putting \bug -# commands in the documentation. - -GENERATE_BUGLIST = YES - -# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or -# disable (NO) the deprecated list. This list is created by putting -# \deprecated commands in the documentation. - -GENERATE_DEPRECATEDLIST= YES - -# The ENABLED_SECTIONS tag can be used to enable conditional -# documentation sections, marked by \if sectionname ... \endif. - -ENABLED_SECTIONS = - -# The MAX_INITIALIZER_LINES tag determines the maximum number of lines -# the initial value of a variable or define consists of for it to appear in -# the documentation. If the initializer consists of more lines than specified -# here it will be hidden. Use a value of 0 to hide initializers completely. -# The appearance of the initializer of individual variables and defines in the -# documentation can be controlled using \showinitializer or \hideinitializer -# command in the documentation regardless of this setting. - -MAX_INITIALIZER_LINES = 30 - -# Set the SHOW_USED_FILES tag to NO to disable the list of files generated -# at the bottom of the documentation of classes and structs. If set to YES the -# list will mention the files that were used to generate the documentation. - -SHOW_USED_FILES = YES - -# If the sources in your project are distributed over multiple directories -# then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy -# in the documentation. The default is NO. - -SHOW_DIRECTORIES = YES - -# The FILE_VERSION_FILTER tag can be used to specify a program or script that -# doxygen should invoke to get the current version for each file (typically from the -# version control system). Doxygen will invoke the program by executing (via -# popen()) the command , where is the value of -# the FILE_VERSION_FILTER tag, and is the name of an input file -# provided by doxygen. Whatever the program writes to standard output -# is used as the file version. See the manual for examples. - -FILE_VERSION_FILTER = - -#--------------------------------------------------------------------------- -# configuration options related to warning and progress messages -#--------------------------------------------------------------------------- - -# The QUIET tag can be used to turn on/off the messages that are generated -# by doxygen. Possible values are YES and NO. If left blank NO is used. - -QUIET = NO - -# The WARNINGS tag can be used to turn on/off the warning messages that are -# generated by doxygen. Possible values are YES and NO. If left blank -# NO is used. - -WARNINGS = YES - -# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings -# for undocumented members. If EXTRACT_ALL is set to YES then this flag will -# automatically be disabled. - -WARN_IF_UNDOCUMENTED = YES - -# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for -# potential errors in the documentation, such as not documenting some -# parameters in a documented function, or documenting parameters that -# don't exist or using markup commands wrongly. - -WARN_IF_DOC_ERROR = YES - -# This WARN_NO_PARAMDOC option can be abled to get warnings for -# functions that are documented, but have no documentation for their parameters -# or return value. If set to NO (the default) doxygen will only warn about -# wrong or incomplete parameter documentation, but not about the absence of -# documentation. - -WARN_NO_PARAMDOC = NO - -# The WARN_FORMAT tag determines the format of the warning messages that -# doxygen can produce. The string should contain the $file, $line, and $text -# tags, which will be replaced by the file and line number from which the -# warning originated and the warning text. Optionally the format may contain -# $version, which will be replaced by the version of the file (if it could -# be obtained via FILE_VERSION_FILTER) - -WARN_FORMAT = "$file:$line: $text" - -# The WARN_LOGFILE tag can be used to specify a file to which warning -# and error messages should be written. If left blank the output is written -# to stderr. - -WARN_LOGFILE = - -#--------------------------------------------------------------------------- -# configuration options related to the input files -#--------------------------------------------------------------------------- - -# The INPUT tag can be used to specify the files and/or directories that contain -# documented source files. You may enter file names like "myfile.cpp" or -# directories like "/usr/src/myproject". Separate the files or directories -# with spaces. - -INPUT = $(FEISTY_MEOW_DIR)/scripts $(FEISTY_MEOW_DIR)/nucleus $(FEISTY_MEOW_DIR)/octopi $(FEISTY_MEOW_DIR)/graphiq $(PRODUCTION_DIR)/setup_src - -# If the value of the INPUT tag contains directories, you can use the -# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp -# and *.h) to filter out the source-files in the directories. If left -# blank the following patterns are tested: -# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx -# *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.py - -FILE_PATTERNS = - -# The RECURSIVE tag can be used to turn specify whether or not subdirectories -# should be searched for input files as well. Possible values are YES and NO. -# If left blank NO is used. - -RECURSIVE = YES - -# The EXCLUDE tag can be used to specify files and/or directories that should -# excluded from the INPUT source files. This way you can easily exclude a -# subdirectory from a directory tree whose root is specified with the INPUT tag. - -EXCLUDE = - -# The EXCLUDE_SYMLINKS tag can be used select whether or not files or -# directories that are symbolic links (a Unix filesystem feature) are excluded -# from the input. - -EXCLUDE_SYMLINKS = NO - -# If the value of the INPUT tag contains directories, you can use the -# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude -# certain files from those directories. Note that the wildcards are matched -# against the file with absolute path, so to exclude all test directories -# for example use the pattern */test/* - -EXCLUDE_PATTERNS = "*/3rdparty/*" "*/clam_bin/*" "*/bin/*" "*/binaries/*" "*/install/*" "*/logs/*" "*/msys/*" "*/objects/*" "*/packages/*" "*/waste/*" - -# The EXAMPLE_PATH tag can be used to specify one or more files or -# directories that contain example code fragments that are included (see -# the \include command). - -EXAMPLE_PATH = - -# If the value of the EXAMPLE_PATH tag contains directories, you can use the -# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp -# and *.h) to filter out the source-files in the directories. If left -# blank all files are included. - -EXAMPLE_PATTERNS = - -# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be -# searched for input files to be used with the \include or \dontinclude -# commands irrespective of the value of the RECURSIVE tag. -# Possible values are YES and NO. If left blank NO is used. - -EXAMPLE_RECURSIVE = NO - -# The IMAGE_PATH tag can be used to specify one or more files or -# directories that contain image that are included in the documentation (see -# the \image command). - -IMAGE_PATH = - -# The INPUT_FILTER tag can be used to specify a program that doxygen should -# invoke to filter for each input file. Doxygen will invoke the filter program -# by executing (via popen()) the command , where -# is the value of the INPUT_FILTER tag, and is the name of an -# input file. Doxygen will then use the output that the filter program writes -# to standard output. If FILTER_PATTERNS is specified, this tag will be -# ignored. - -INPUT_FILTER = - -# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern -# basis. Doxygen will compare the file name with each pattern and apply the -# filter if there is a match. The filters are a list of the form: -# pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further -# info on how filters are used. If FILTER_PATTERNS is empty, INPUT_FILTER -# is applied to all files. - -FILTER_PATTERNS = - -# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using -# INPUT_FILTER) will be used to filter the input files when producing source -# files to browse (i.e. when SOURCE_BROWSER is set to YES). - -FILTER_SOURCE_FILES = NO - -#--------------------------------------------------------------------------- -# configuration options related to source browsing -#--------------------------------------------------------------------------- - -# If the SOURCE_BROWSER tag is set to YES then a list of source files will -# be generated. Documented entities will be cross-referenced with these sources. -# Note: To get rid of all source code in the generated output, make sure also -# VERBATIM_HEADERS is set to NO. - -SOURCE_BROWSER = YES - -# Setting the INLINE_SOURCES tag to YES will include the body -# of functions and classes directly in the documentation. - -INLINE_SOURCES = NO - -# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct -# doxygen to hide any special comment blocks from generated source code -# fragments. Normal C and C++ comments will always remain visible. - -STRIP_CODE_COMMENTS = YES - -# If the REFERENCED_BY_RELATION tag is set to YES (the default) -# then for each documented function all documented -# functions referencing it will be listed. - -REFERENCED_BY_RELATION = YES - -# If the REFERENCES_RELATION tag is set to YES (the default) -# then for each documented function all documented entities -# called/used by that function will be listed. - -REFERENCES_RELATION = YES - -# If the REFERENCES_LINK_SOURCE tag is set to YES (the default) -# and SOURCE_BROWSER tag is set to YES, then the hyperlinks from -# functions in REFERENCES_RELATION and REFERENCED_BY_RELATION lists will -# link to the source code. Otherwise they will link to the documentstion. - -REFERENCES_LINK_SOURCE = YES - -# If the USE_HTAGS tag is set to YES then the references to source code -# will point to the HTML generated by the htags(1) tool instead of doxygen -# built-in source browser. The htags tool is part of GNU's global source -# tagging system (see http://www.gnu.org/software/global/global.html). You -# will need version 4.8.6 or higher. - -USE_HTAGS = NO - -# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen -# will generate a verbatim copy of the header file for each class for -# which an include is specified. Set to NO to disable this. - -VERBATIM_HEADERS = YES - -#--------------------------------------------------------------------------- -# configuration options related to the alphabetical class index -#--------------------------------------------------------------------------- - -# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index -# of all compounds will be generated. Enable this if the project -# contains a lot of classes, structs, unions or interfaces. - -ALPHABETICAL_INDEX = YES - -# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then -# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns -# in which this list will be split (can be a number in the range [1..20]) - -COLS_IN_ALPHA_INDEX = 5 - -# In case all classes in a project start with a common prefix, all -# classes will be put under the same header in the alphabetical index. -# The IGNORE_PREFIX tag can be used to specify one or more prefixes that -# should be ignored while generating the index headers. - -IGNORE_PREFIX = - -#--------------------------------------------------------------------------- -# configuration options related to the HTML output -#--------------------------------------------------------------------------- - -# If the GENERATE_HTML tag is set to YES (the default) Doxygen will -# generate HTML output. - -GENERATE_HTML = YES - -# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `html' will be used as the default path. - -HTML_OUTPUT = $(PRODUCTION_DIR)/code_guide - -# The HTML_FILE_EXTENSION tag can be used to specify the file extension for -# each generated HTML page (for example: .htm,.php,.asp). If it is left blank -# doxygen will generate files with .html extension. - -HTML_FILE_EXTENSION = .html - -# The HTML_HEADER tag can be used to specify a personal HTML header for -# each generated HTML page. If it is left blank doxygen will generate a -# standard header. - -HTML_HEADER = - -# The HTML_FOOTER tag can be used to specify a personal HTML footer for -# each generated HTML page. If it is left blank doxygen will generate a -# standard footer. - -HTML_FOOTER = - -# The HTML_STYLESHEET tag can be used to specify a user-defined cascading -# style sheet that is used by each HTML page. It can be used to -# fine-tune the look of the HTML output. If the tag is left blank doxygen -# will generate a default style sheet. Note that doxygen will try to copy -# the style sheet file to the HTML output directory, so don't put your own -# stylesheet in the HTML output directory as well, or it will be erased! - -HTML_STYLESHEET = - -# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes, -# files or namespaces will be aligned in HTML using tables. If set to -# NO a bullet list will be used. - -HTML_ALIGN_MEMBERS = YES - -# If the GENERATE_HTMLHELP tag is set to YES, additional index files -# will be generated that can be used as input for tools like the -# Microsoft HTML help workshop to generate a compressed HTML help file (.chm) -# of the generated HTML documentation. - -GENERATE_HTMLHELP = NO - -# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can -# be used to specify the file name of the resulting .chm file. You -# can add a path in front of the file if the result should not be -# written to the html output directory. - -CHM_FILE = - -# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can -# be used to specify the location (absolute path including file name) of -# the HTML help compiler (hhc.exe). If non-empty doxygen will try to run -# the HTML help compiler on the generated index.hhp. - -HHC_LOCATION = - -# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag -# controls if a separate .chi index file is generated (YES) or that -# it should be included in the master .chm file (NO). - -GENERATE_CHI = NO - -# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag -# controls whether a binary table of contents is generated (YES) or a -# normal table of contents (NO) in the .chm file. - -BINARY_TOC = NO - -# The TOC_EXPAND flag can be set to YES to add extra items for group members -# to the contents of the HTML help documentation and to the tree view. - -TOC_EXPAND = NO - -# The DISABLE_INDEX tag can be used to turn on/off the condensed index at -# top of each HTML page. The value NO (the default) enables the index and -# the value YES disables it. - -DISABLE_INDEX = NO - -# This tag can be used to set the number of enum values (range [1..20]) -# that doxygen will group on one line in the generated HTML documentation. - -ENUM_VALUES_PER_LINE = 4 - -# If the GENERATE_TREEVIEW tag is set to YES, a side panel will be -# generated containing a tree-like index structure (just like the one that -# is generated for HTML Help). For this to work a browser that supports -# JavaScript, DHTML, CSS and frames is required (for instance Mozilla 1.0+, -# Netscape 6.0+, Internet explorer 5.0+, or Konqueror). Windows users are -# probably better off using the HTML help feature. - -GENERATE_TREEVIEW = YES - -# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be -# used to set the initial width (in pixels) of the frame in which the tree -# is shown. - -TREEVIEW_WIDTH = 250 - -#--------------------------------------------------------------------------- -# configuration options related to the LaTeX output -#--------------------------------------------------------------------------- - -# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will -# generate Latex output. - -GENERATE_LATEX = NO - -# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `latex' will be used as the default path. - -LATEX_OUTPUT = latex - -# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be -# invoked. If left blank `latex' will be used as the default command name. - -LATEX_CMD_NAME = latex - -# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to -# generate index for LaTeX. If left blank `makeindex' will be used as the -# default command name. - -MAKEINDEX_CMD_NAME = makeindex - -# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact -# LaTeX documents. This may be useful for small projects and may help to -# save some trees in general. - -COMPACT_LATEX = NO - -# The PAPER_TYPE tag can be used to set the paper type that is used -# by the printer. Possible values are: a4, a4wide, letter, legal and -# executive. If left blank a4wide will be used. - -PAPER_TYPE = a4wide - -# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX -# packages that should be included in the LaTeX output. - -EXTRA_PACKAGES = - -# The LATEX_HEADER tag can be used to specify a personal LaTeX header for -# the generated latex document. The header should contain everything until -# the first chapter. If it is left blank doxygen will generate a -# standard header. Notice: only use this tag if you know what you are doing! - -LATEX_HEADER = - -# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated -# is prepared for conversion to pdf (using ps2pdf). The pdf file will -# contain links (just like the HTML output) instead of page references -# This makes the output suitable for online browsing using a pdf viewer. - -PDF_HYPERLINKS = NO - -# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of -# plain latex in the generated Makefile. Set this option to YES to get a -# higher quality PDF documentation. - -USE_PDFLATEX = NO - -# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode. -# command to the generated LaTeX files. This will instruct LaTeX to keep -# running if errors occur, instead of asking the user for help. -# This option is also used when generating formulas in HTML. - -LATEX_BATCHMODE = NO - -# If LATEX_HIDE_INDICES is set to YES then doxygen will not -# include the index chapters (such as File Index, Compound Index, etc.) -# in the output. - -LATEX_HIDE_INDICES = NO - -#--------------------------------------------------------------------------- -# configuration options related to the RTF output -#--------------------------------------------------------------------------- - -# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output -# The RTF output is optimized for Word 97 and may not look very pretty with -# other RTF readers or editors. - -GENERATE_RTF = NO - -# The RTF_OUTPUT tag is used to specify where the RTF docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `rtf' will be used as the default path. - -RTF_OUTPUT = rtf - -# If the COMPACT_RTF tag is set to YES Doxygen generates more compact -# RTF documents. This may be useful for small projects and may help to -# save some trees in general. - -COMPACT_RTF = NO - -# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated -# will contain hyperlink fields. The RTF file will -# contain links (just like the HTML output) instead of page references. -# This makes the output suitable for online browsing using WORD or other -# programs which support those fields. -# Note: wordpad (write) and others do not support links. - -RTF_HYPERLINKS = NO - -# Load stylesheet definitions from file. Syntax is similar to doxygen's -# config file, i.e. a series of assignments. You only have to provide -# replacements, missing definitions are set to their default value. - -RTF_STYLESHEET_FILE = - -# Set optional variables used in the generation of an rtf document. -# Syntax is similar to doxygen's config file. - -RTF_EXTENSIONS_FILE = - -#--------------------------------------------------------------------------- -# configuration options related to the man page output -#--------------------------------------------------------------------------- - -# If the GENERATE_MAN tag is set to YES (the default) Doxygen will -# generate man pages - -GENERATE_MAN = NO - -# The MAN_OUTPUT tag is used to specify where the man pages will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `man' will be used as the default path. - -MAN_OUTPUT = man - -# The MAN_EXTENSION tag determines the extension that is added to -# the generated man pages (default is the subroutine's section .3) - -MAN_EXTENSION = .3 - -# If the MAN_LINKS tag is set to YES and Doxygen generates man output, -# then it will generate one additional man file for each entity -# documented in the real man page(s). These additional files -# only source the real man page, but without them the man command -# would be unable to find the correct page. The default is NO. - -MAN_LINKS = NO - -#--------------------------------------------------------------------------- -# configuration options related to the XML output -#--------------------------------------------------------------------------- - -# If the GENERATE_XML tag is set to YES Doxygen will -# generate an XML file that captures the structure of -# the code including all documentation. - -GENERATE_XML = NO - -# The XML_OUTPUT tag is used to specify where the XML pages will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `xml' will be used as the default path. - -XML_OUTPUT = xml - -# The XML_SCHEMA tag can be used to specify an XML schema, -# which can be used by a validating XML parser to check the -# syntax of the XML files. - -XML_SCHEMA = - -# The XML_DTD tag can be used to specify an XML DTD, -# which can be used by a validating XML parser to check the -# syntax of the XML files. - -XML_DTD = - -# If the XML_PROGRAMLISTING tag is set to YES Doxygen will -# dump the program listings (including syntax highlighting -# and cross-referencing information) to the XML output. Note that -# enabling this will significantly increase the size of the XML output. - -XML_PROGRAMLISTING = YES - -#--------------------------------------------------------------------------- -# configuration options for the AutoGen Definitions output -#--------------------------------------------------------------------------- - -# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will -# generate an AutoGen Definitions (see autogen.sf.net) file -# that captures the structure of the code including all -# documentation. Note that this feature is still experimental -# and incomplete at the moment. - -GENERATE_AUTOGEN_DEF = NO - -#--------------------------------------------------------------------------- -# configuration options related to the Perl module output -#--------------------------------------------------------------------------- - -# If the GENERATE_PERLMOD tag is set to YES Doxygen will -# generate a Perl module file that captures the structure of -# the code including all documentation. Note that this -# feature is still experimental and incomplete at the -# moment. - -GENERATE_PERLMOD = NO - -# If the PERLMOD_LATEX tag is set to YES Doxygen will generate -# the necessary Makefile rules, Perl scripts and LaTeX code to be able -# to generate PDF and DVI output from the Perl module output. - -PERLMOD_LATEX = NO - -# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be -# nicely formatted so it can be parsed by a human reader. This is useful -# if you want to understand what is going on. On the other hand, if this -# tag is set to NO the size of the Perl module output will be much smaller -# and Perl will parse it just the same. - -PERLMOD_PRETTY = YES - -# The names of the make variables in the generated doxyrules.make file -# are prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX. -# This is useful so different doxyrules.make files included by the same -# Makefile don't overwrite each other's variables. - -PERLMOD_MAKEVAR_PREFIX = - -#--------------------------------------------------------------------------- -# Configuration options related to the preprocessor -#--------------------------------------------------------------------------- - -# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will -# evaluate all C-preprocessor directives found in the sources and include -# files. - -ENABLE_PREPROCESSING = YES - -# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro -# names in the source code. If set to NO (the default) only conditional -# compilation will be performed. Macro expansion can be done in a controlled -# way by setting EXPAND_ONLY_PREDEF to YES. - -MACRO_EXPANSION = NO - -# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES -# then the macro expansion is limited to the macros specified with the -# PREDEFINED and EXPAND_AS_DEFINED tags. - -EXPAND_ONLY_PREDEF = NO - -# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files -# in the INCLUDE_PATH (see below) will be search if a #include is found. - -SEARCH_INCLUDES = YES - -# The INCLUDE_PATH tag can be used to specify one or more directories that -# contain include files that are not input files but should be processed by -# the preprocessor. - -INCLUDE_PATH = - -# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard -# patterns (like *.h and *.hpp) to filter out the header-files in the -# directories. If left blank, the patterns specified with FILE_PATTERNS will -# be used. - -INCLUDE_FILE_PATTERNS = - -# The PREDEFINED tag can be used to specify one or more macro names that -# are defined before the preprocessor is started (similar to the -D option of -# gcc). The argument of the tag is a list of macros of the form: name -# or name=definition (no spaces). If the definition and the = are -# omitted =1 is assumed. To prevent a macro definition from being -# undefined via #undef or recursively expanded use the := operator -# instead of the = operator. - -PREDEFINED = $(DEFINITIONS) - -# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then -# this tag can be used to specify a list of macro names that should be expanded. -# The macro definition that is found in the sources will be used. -# Use the PREDEFINED tag if you want to use a different macro definition. - -EXPAND_AS_DEFINED = - -# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then -# doxygen's preprocessor will remove all function-like macros that are alone -# on a line, have an all uppercase name, and do not end with a semicolon. Such -# function macros are typically used for boiler-plate code, and will confuse -# the parser if not removed. - -SKIP_FUNCTION_MACROS = YES - -#--------------------------------------------------------------------------- -# Configuration::additions related to external references -#--------------------------------------------------------------------------- - -# The TAGFILES option can be used to specify one or more tagfiles. -# Optionally an initial location of the external documentation -# can be added for each tagfile. The format of a tag file without -# this location is as follows: -# TAGFILES = file1 file2 ... -# Adding location for the tag files is done as follows: -# TAGFILES = file1=loc1 "file2 = loc2" ... -# where "loc1" and "loc2" can be relative or absolute paths or -# URLs. If a location is present for each tag, the installdox tool -# does not have to be run to correct the links. -# Note that each tag file must have a unique name -# (where the name does NOT include the path) -# If a tag file is not located in the directory in which doxygen -# is run, you must also specify the path to the tagfile here. - -TAGFILES = - -# When a file name is specified after GENERATE_TAGFILE, doxygen will create -# a tag file that is based on the input files it reads. - -GENERATE_TAGFILE = - -# If the ALLEXTERNALS tag is set to YES all external classes will be listed -# in the class index. If set to NO only the inherited external classes -# will be listed. - -ALLEXTERNALS = NO - -# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed -# in the modules index. If set to NO, only the current project's groups will -# be listed. - -EXTERNAL_GROUPS = YES - -# The PERL_PATH should be the absolute path and name of the perl script -# interpreter (i.e. the result of `which perl'). - -PERL_PATH = /usr/bin/perl - -#--------------------------------------------------------------------------- -# Configuration options related to the dot tool -#--------------------------------------------------------------------------- - -# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will -# generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base -# or super classes. Setting the tag to NO turns the diagrams off. Note that -# this option is superseded by the HAVE_DOT option below. This is only a -# fallback. It is recommended to install and use dot, since it yields more -# powerful graphs. - -CLASS_DIAGRAMS = YES - -# If set to YES, the inheritance and collaboration graphs will hide -# inheritance and usage relations if the target is undocumented -# or is not a class. - -HIDE_UNDOC_RELATIONS = YES - -# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is -# available from the path. This tool is part of Graphviz, a graph visualization -# toolkit from AT&T and Lucent Bell Labs. The other options in this section -# have no effect if this option is set to NO (the default) - -HAVE_DOT = YES - -# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen -# will generate a graph for each documented class showing the direct and -# indirect inheritance relations. Setting this tag to YES will force the -# the CLASS_DIAGRAMS tag to NO. - -CLASS_GRAPH = YES - -# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen -# will generate a graph for each documented class showing the direct and -# indirect implementation dependencies (inheritance, containment, and -# class references variables) of the class with other documented classes. - -COLLABORATION_GRAPH = YES - -# If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen -# will generate a graph for groups, showing the direct groups dependencies - -GROUP_GRAPHS = YES - -# If the UML_LOOK tag is set to YES doxygen will generate inheritance and -# collaboration diagrams in a style similar to the OMG's Unified Modeling -# Language. - -UML_LOOK = NO - -# If set to YES, the inheritance and collaboration graphs will show the -# relations between templates and their instances. - -TEMPLATE_RELATIONS = NO - -# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT -# tags are set to YES then doxygen will generate a graph for each documented -# file showing the direct and indirect include dependencies of the file with -# other documented files. - -INCLUDE_GRAPH = YES - -# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and -# HAVE_DOT tags are set to YES then doxygen will generate a graph for each -# documented header file showing the documented files that directly or -# indirectly include this file. - -INCLUDED_BY_GRAPH = YES - -# If the CALL_GRAPH and HAVE_DOT tags are set to YES then doxygen will -# generate a call dependency graph for every global function or class method. -# Note that enabling this option will significantly increase the time of a run. -# So in most cases it will be better to enable call graphs for selected -# functions only using the \callgraph command. - -CALL_GRAPH = NO - -# If the CALLER_GRAPH and HAVE_DOT tags are set to YES then doxygen will -# generate a caller dependency graph for every global function or class method. -# Note that enabling this option will significantly increase the time of a run. -# So in most cases it will be better to enable caller graphs for selected -# functions only using the \callergraph command. - -CALLER_GRAPH = NO - -# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen -# will graphical hierarchy of all classes instead of a textual one. - -GRAPHICAL_HIERARCHY = YES - -# If the DIRECTORY_GRAPH, SHOW_DIRECTORIES and HAVE_DOT tags are set to YES -# then doxygen will show the dependencies a directory has on other directories -# in a graphical way. The dependency relations are determined by the #include -# relations between the files in the directories. - -DIRECTORY_GRAPH = YES - -# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images -# generated by dot. Possible values are png, jpg, or gif -# If left blank png will be used. - -DOT_IMAGE_FORMAT = png - -# The tag DOT_PATH can be used to specify the path where the dot tool can be -# found. If left blank, it is assumed the dot tool can be found in the path. - -DOT_PATH = /usr/bin - -# The DOTFILE_DIRS tag can be used to specify one or more directories that -# contain dot files that are included in the documentation (see the -# \dotfile command). - -DOTFILE_DIRS = - -# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the -# graphs generated by dot. A depth value of 3 means that only nodes reachable -# from the root by following a path via at most 3 edges will be shown. Nodes -# that lay further from the root node will be omitted. Note that setting this -# option to 1 or 2 may greatly reduce the computation time needed for large -# code bases. Also note that a graph may be further truncated if the graph's -# image dimensions are not sufficient to fit the graph (see MAX_DOT_GRAPH_WIDTH -# and MAX_DOT_GRAPH_HEIGHT). If 0 is used for the depth value (the default), -# the graph is not depth-constrained. - -MAX_DOT_GRAPH_DEPTH = 0 - -# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent -# background. This is disabled by default, which results in a white background. -# Warning: Depending on the platform used, enabling this option may lead to -# badly anti-aliased labels on the edges of a graph (i.e. they become hard to -# read). - -DOT_TRANSPARENT = NO - -# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output -# files in one run (i.e. multiple -o and -T options on the command line). This -# makes dot run faster, but since only newer versions of dot (>1.8.10) -# support this, this feature is disabled by default. - -DOT_MULTI_TARGETS = NO - -# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will -# generate a legend page explaining the meaning of the various boxes and -# arrows in the dot generated graphs. - -GENERATE_LEGEND = YES - -# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will -# remove the intermediate dot files that are used to generate -# the various graphs. - -DOT_CLEANUP = YES - -#--------------------------------------------------------------------------- -# Configuration::additions related to the search engine -#--------------------------------------------------------------------------- - -# The SEARCHENGINE tag specifies whether or not a search engine should be -# used. If set to NO the values of all tags below this one will be ignored. - -SEARCHENGINE = NO diff --git a/docs/feisty_meow_quick_start.txt b/docs/feisty_meow_quick_start.txt deleted file mode 100644 index 6d24456b..00000000 --- a/docs/feisty_meow_quick_start.txt +++ /dev/null @@ -1,74 +0,0 @@ - -Feisty Meow Concerns Ltd. is a small software shop that concentrates on building high quality, -portable, open source projects in a variety of languages (primarily bash, perl, python, C++, -and Java). Here are some highlights of our main products: - - Bookmark Processing Tools - can take a mozilla bookmark file or arbitrary - web page and extract all the links out of it, building a csv database of - web links. Using that database, a variety of output formats are - provided, including one that outputs a mozilla bookmark file again. - The most useful feature is probably the marks checker that operates on - our csv format and that locates all unreachable links in the file and - separates them out. - - CROMP protocol - supports transmission of objects across the network and - provides a platform independent method for RPC and other types of - communication. - - Octopus design pattern - the underpinning of the CROMP protocol. An octopus - has an arbitrary number of tentacles (no, not just eight) which are each - responsible for consuming a different type of object (or datum). - - Fast Templates and Portable Abstractions - the class libraries of Feisty Meow - provide numerous different data structures and programming language - abstractions (like threads and state machines). There are also some - fairly ancient templates (in use since late 80s) which in many cases - perform faster than their STL analogues. - - CLAM System - Feisty Meow is the home site of the CLAM makefile system. The - CLAM system is a flexible and extensible method for building C++ and - C# files using makefiles. - -Prerequisites: - - Software required to compile under Linux: - curl-devel - openmotif-devel - openssl-devel - wxGTK-devel - - Software required to compiler under MS-windows: - The free Microsoft compiler should build Feisty Meow but it is untested. - The full version of MS Visual Studio 2010 (version 10) is supported. - Gnu C++ should compile Feisty Meow but it is also untested recently. - -Quick Start: - - Run the following commands to bootstrap the Feisty Meow libraries, once you - have downloaded the archive or retrieved them via CVS (assuming that you - have stored the files in ~/feisty_meow): - - bash ~/feisty_meow2/scripts/generator/bootstrap_build.sh - - This should create the 'makedep' dependency checking tool and the version - tagging tool and then go through the rest of the build. - - Once you've got a bootstrapped build, you can clean out all the files with: - - bash ~/feisty_meow2/scripts/generator/whack_build.sh clean - - And if you want to load the build environment for doing makes inside the - feisty_meow hierarchies, you can either run a sub-shell with the environment: - - bash ~/feisty_meow2/scripts/generator/build_variables.sh - - or you can load them into the current shell: - - bv=~/feisty_meow2/scripts/generator/build_variables.sh; source $bv $bv - - (The double reference is required since a sourced script does not get any of - the command-line parameters from the parent script.) - - More information is available at the official site http://feistymeow.org - - diff --git a/docs/makefile b/docs/makefile deleted file mode 100644 index ae493d94..00000000 --- a/docs/makefile +++ /dev/null @@ -1,17 +0,0 @@ - -export DEFINITIONS - # ensure that the macros get passed down to the subprocesses. - -include cpp/variables.def - -PROJECT = Source_Documentation -TYPE = application -FIRST_TARGETS = build_doxygen -CLEANUPS = html - -include cpp/rules.def - -build_doxygen: - @echo the defs are $(DEFINITIONS) - doxygen $(wildcard *.config) - diff --git a/docs/perl_tools.html b/docs/perl_tools.html deleted file mode 100644 index 5c2c932e..00000000 --- a/docs/perl_tools.html +++ /dev/null @@ -1,372 +0,0 @@ - - - - - - - - - YETIcode Perl Scripts - - - - -

 

-
- - - - - - -
-
-

YETIcode Open Source Perl -Scripts

-

Some Hopefully Useful GPL-Licensed Perl Code
-

-
-
Contributed by Chris Koeritz (Koeritz@Gruntose.COM)
-See the GNU Public -License for details of licensing.
-
-

Caveats:

-
    -
  1. No warranty, express, implied or imagined, is offered for -these files.  If you destroy your life by running one of them, I -will have sympathy, but that's about it.
    2. -
  2. Some of these shell scripts depend on environment variables.  -The most frequent case of this is FEISTY_MEOW_DIR, which should point to the -top-level -directory where the YETIcode scripts are stored on your -machine.   This variable is set by default when the scripts are in -the ~/yeti folder.  Consult your operating -system documentation if you are -unfamiliar with the concept or management of environment variables.
    3. -
  3. These files are provided as possibly useful shell scripts -rather than as full-fledged reusable and object oriented components.
    4. -
  4. Improvements and contributions are gladly accepted.  -They will be processed as fast as our schedule permits.  Please -send any changes to the Gruntose Curator at fred@gruntose.com .
    5. -
  5. These files are mostly portable between Unix and the -various Windoze OSes, but in many cases you may want to fix the -defaults or path names to make them more suitable for your own needs.
    6. -
  6. Some of the scripts invoke external programs that are -available for most Unixes.  For Windoze users, a set of GNU Unix -utilities is available at "http://www.mingw.org/".
    7. -
  7. An alternative, but not recommended, GNU suite is -at "http://www.cygwin.com/".
    8. -
  8. Direct Cognition: -View the scripts directory itself rather than navigating with the links -below: scripts.
    9. -
-
-
-

 

-
- - - - - - -
-

Library Files
-

-
-

diff_lib.pl

-
The "differ" utilities can be used to compare two -directories of text or binary files against each other.  The two -directories are presumably close in contents.  This can be useful -when one is revising a set of files and wants to synchronize an older -copy against a newer version.  Support for "differ.pl" -is provided -here.
-

filename_helper.pl

-
Contains a handy set of utilities for manipulating -filenames.  These can help to make perl scripts portable across -the two well-known types of filename separators ('/' and '\').  -They also provide support for ripping up filenames into their -components.
-

inc_num.pl

-
This is a simple utility that manages a file with a -number in it.  This is somewhat more useful than it sounds.  -Functions are provided to get the current number and to change the -number.
-

-

shared_snarfer.pl

-
This library supports the "snarf" utilities.  -The -utilities manipulate archive files with the ".snarf" extension.  -These -packed -snarf files are compressed chunks of directory hierarchies.  Bob -files -are useful because they track a number per distinct "snarf" types that -is -used to make uniquely named new archives of the appropriate type.  -This -number is an ever increasing integer that's stored in a well-known -(configurable) location.  When a snarf file is unpacked (using the -"unsnarf" tool), the number is updated on the local machine so that the -next generated file will -be one greater than the previous number.  If one is travelling -between -two machines with the same snarf file, this will have the effect of -keeping -the number updated on both sides. -
-

zap_the_dir.pl

-
Support for the zapdirs utility.  This library -cleans out the directory that it is passed by removing files that are -not considered important (using "filename_helper.pl -").  The list of important files is something you might want to -look at to ensure that you won't get burned by zapdirs.
-
-
-
-

 

-
- - - - - - -
-

Applications

-
-

add_cr.pl

-
Processes Unix format text files for pcdos by -forcing the line endings to be Carriage Return plus Line Feed (CRLF).
-

-

cgi_display.pl

-
Turns the files passed on the command line into a -stream of CGI compatible text output. The javascript show_file method -(see the -source for this page) is preferred since it is lighter weight and -doesn't -need cgi, but there are some situations where cgi is the only option -(older -browsers or requirements of no javascript).
-

-

change_endings.pl

-
Replaces the suffix of all filenames in the current -directory -with a different suffix.  Suffix here is defined as the set of -characters -after the last period ('.') in the name.  Note this will not work -for -names without suffices.
-

-

cpdiff.pl

-
Copies files from a source directory into a -destination directory.  The files are only copied when they are -missing in the destination or when the destination version has -different contents.  The syntax looks like this:
-    cpdiff  source  destination
-The assumption is that the files in the source directory are somehow -better, newer or more complete than the set of files in the destination.
-
-

cpdiffnow.pl

-
Similar to cpdiff, but this utility sets the -destination file's time stamp to "now".  This should cause the new -or changed files in the destination directory to be more recent than -anything else in there.  This is helpful sometimes for forcing -compilation of modified source files.
-
-

-

cvs_fix.pl

-
Wraps the cygwin cvs command for pcdos/win32. - Any -unfriendly backward slashes are flipped to be forward slashes.
-
-

-

differ.pl

-
Compares two directory hierarchies and the files -they -contain.  The first parameter is a directory -to compare against "this" directory; -every subdirectory "here" will be traversed in order to build the -output file that shows the differences.  An optional second -argument can be used to specify a different directory than the current -one as the source of the comparison (the first argument is always the -destination of the comparison).
-

filedump.pl

-
Collects the contents of the files whose names are -passed on the command line into one gigundo stream which is passed to -standard output. The output can be piped into another file as desired.
-

generate_aliases.pl

-
Performs some useful activities for the YETI shell -environment.  Using the environment variable for FEISTY_MEOW_SCRIPTS (which -is set in the appropriate startup files to be the shell scripts -directory, where all this stuff lives), generate_aliases will create -all of the aliases files for the combinations of operating systems and -types of shells supported.  Currently this includes Linux, Unix, -PCDOS, OS/2 and MS-WIN32 (9x, NT, 2K, XP, etc) for -supported operating systems.  The shell languages supported are -dos's command, nt's cmd, unix's sh and bash, and perl.  This script will also look for -any files ending in ".sh" or ".pl" and it will create aliases for them -in forms appropriate to the different shells.  The .zz_auto_gen -subdirectory -is created under the home directory (or under TMP in DOS and Win32) as -a storage place for the generated -files.
-

-

goodbye.pl

-
A logout script for exiting from a shell; it prints -a message using the nechung oracle for the user's benefit and starts a -byejob before exiting. The byejob will wait for a few seconds, then -clear the screen and print another fortune. It attempts to leave the -screen looking like a -standard login, but with an extra fortune.
-

-

-

new_sig.pl

-
Generates a signature file from the nechung -database -using the 'nechung' application.  See the HOOPLE library for the nechung -application. - The database for nechung resides in the whole -YETI -package in "yeti/database".
-

-

renlower.pl

-
Renames all of the files passed on the command line -such that they are only in lower-case.  Useful if you're tired of -passing mistakenly re-capitalized names from a defective 8.3 OS (e.g. -Doze95/98) to -a file system where you care about the case.
-

runner.pl

-
Finds all executable files in the current directory -(and subdirectories) and runs them.  The output of the programs is -sent to standard output.  Standard error is used to report which -file is being worked on, plus the running programs' own standard error -streams are merged into runner's standard error stream.  This -makes it nice to do something like:
-       runner >runs.log
-where the runs.log file will contain the output of each program that -was executed and the console will be sent messages as each program is -started and finished (and errors show up at the console also).
-
-

safedel.pl

-
Makes deleting files and directories a little less -nerve-wracking.  If you substitute safedel as an alias for rm or -del or deltree or whatever, it will make a zipped backup of the items -before they are actually deleted.  Safedel keeps track of a number -that is attached to each zip to enforce uniquely numbered -archives.  They are stored in a directory named "zz_del_keep" -that is stored under the temorary directory (specified by the -environment -variable named TMP).  A report of the contents of the compressed -trash -is appended to a file named "zz_safedel.rpt" in the TMP directory.  -Occasional -cleaning of the deleted files folder is recommend, but this utility has -saved -my various parts several times already.
-

-

-

snarf_linux_config.pl

-
A snarf utility that packages up the -important configuration files in a Linux installation.
-

-

snarf_light.pl

-
A selective snarf of the source hierarchy.  -This -collects the code that I manage.  As such, this is probably -irrelevant to anyone but CAK.
-

snarf_notes.pl

-
Gathers all "important" files from the home -directory. - This -is somewhat personally tuned but it includes files and directories that -have -"project", "notes", or "crucial" in their name.
-

-

snarf_src.pl

-
A source code grabbing snarfer.  The entire -source -code hierarchy is snarfed.  Note that one should edit the -hierarchy -location to make it appropriate for your local source code.
-

-

snarf_yeti.pl

-
A snarfer for the YETI shell scripts and databases.
-

summing_dir.pl

-
Offers a directory listing along with total file -sizes -and disk free space.
-
-
-

synch_build.pl

-
This is a helper utility that synchronizes the binary -outputs from a build process with an existing installed location.  Given a target directory, the executable -programs and dynamic libraries that exist there will be synchronized -with the build repository's versions.  This is kind of a quickie -upgrade process, as long as the files in the target location are not -locked by other processes.
-
-

unsnarf.pl

-
Uses the snarfer utilities to undo a previously -snarfed file.  A folder named "snarf_BASE" is created for the -contents, where BASE -is replaced with the basename of the snarf file (that is, without the -".snarf" -suffix).  The number that tracks the snarf files of this type is -updated -such that the next snarf file will be at least one higher than this -snarf's -sorta -unique number.  The number will be managed correctly if you're -always -unsnarfing the most recent snarf files before creating any new snarfs.
-

-

whack_forever.pl

-
Since all of my file deletion commands are aliases -to safedel, it is hard to actually remove a -file.  If I'm really really sure that a file or directory needs to -be -permanently deleted, then this command can be used.  It shows the -names -it is removing also, but it does _not_ ask for confirmation.
-

-

y2038_check.pl

-
Tests the system for survival -past the year 2038, which is when the Unix time scale runs out of bits -for the number of seconds since 1970 measured in a 32 bit integer.
-
-

zapdirs.pl

-
Removes empty directories and directories -containing only -unimportant crud (see "filename_helper.pl").  -If there are no arguments, then the current directory is cleaned up; -any subdirectories -will be traversed into and removed if it seems appropriate.  -Otherwise, -zapdirs operates on the arguments passed to it as if they are directory -names -to be cleaned.
-
-
-

 

-
- - diff --git a/docs/text_examples/chinese_simplified_text.txt b/docs/text_examples/chinese_simplified_text.txt deleted file mode 100644 index 1219fd33..00000000 --- a/docs/text_examples/chinese_simplified_text.txt +++ /dev/null @@ -1,10 +0,0 @@ - -we will translate this at babelfish: - -Let us see then if we can narrow it down. As I focus my mind upon it, it seems rather less impenetrable. What indications have we as to this book? - -into this: - -让我们然后看如果我们能使它狭窄击倒。因为我聚焦我的头脑在它, 它似乎宁可较不难贯穿。什么征兆有我们至于这本书? - - diff --git a/docs/text_examples/korean_text.txt b/docs/text_examples/korean_text.txt deleted file mode 100644 index 52be2983..00000000 --- a/docs/text_examples/korean_text.txt +++ /dev/null @@ -1,12 +0,0 @@ - - -we will translate this at babelfish: - -Let us see then if we can narrow it down. As I focus my mind upon it, it seems rather less impenetrable. What indications have we as to this book? - -into this: - -우리들을 그때 우리가 떨어뜨리기 위하여 그것을 좁힐 수 있으면 보는 시키십시요. 나가 그것에 나의 마음을 초점을 맞추기 때문에, 오히려 보다 적게 보인다. 이 책에 관해서는 무슨 표시가 우리가 있는가? - - - diff --git a/docs/text_examples/readme.txt b/docs/text_examples/readme.txt deleted file mode 100644 index 0111f86c..00000000 --- a/docs/text_examples/readme.txt +++ /dev/null @@ -1,7 +0,0 @@ - - -these are example files of other languages in utf-8 format. - -they can be used to test proper handling of the characters in hoople code. - - diff --git a/docs/text_examples/russian_text.txt b/docs/text_examples/russian_text.txt deleted file mode 100644 index 4ef6c44b..00000000 --- a/docs/text_examples/russian_text.txt +++ /dev/null @@ -1,4 +0,0 @@ - -Stanislav Yevgrafovich Petrov (Russian: Станислав Евграфович Петров) (born c. 1939) is a retired Russian Strategic Rocket Forces lieutenant colonel who, on September 26, 1983, averted a potential nuclear war by refusing to believe that the United States had launched missiles against the Soviet Union, despite the indications given by his computerized early warning systems.[1] - - diff --git a/docs/text_examples/tibetan_text.txt b/docs/text_examples/tibetan_text.txt deleted file mode 100644 index 321ddace..00000000 --- a/docs/text_examples/tibetan_text.txt +++ /dev/null @@ -1,13 +0,0 @@ - - -om mani padme hum: -ༀ'མཎི'པདེྨ'ཧཱུྃ ༔ - - -this was scarfed from a tibetan resources page: - - -༄༅།།གངས་ལྗོངས་གློག་རྡུལ་དཔེ་མཛོད་ཁང་ཞེས་པ་འདི་དེང་དུས་ཀྱི་ འཕྲུལ་རྩལ་བེད་སྤྱད་དེ་ཁ་བའི་ལྗོངས་དང་འབྲེལ་ཡོད་ཀྱི་རིག་ གཞུང་ངོ་མཚར་ཅན་རྣམས་འཛམ་གླིང་ཡུལ་གྲུ་རིས་མེད་ཀྱི་སྐྱེ་བོའི་ སྤྱན་ལམ་དུ་བསྟར་བའི་རིན་གོང་མེད་པའི་དྲ་བའི་སྟེགས་བུ་ཞིག་ ཡིན། ངེད་ཚོས་དྲ་ལམ་དེ་བརྒྱུད་སྐད་རིགས་མི་འདྲ་བའི་ཐོག་ནས་ཁུལ་ དེའི་དཔྱད་གཞིའི་ཡིག་ཆ་སྣ་ཚོགས་མཁོ་འདོན་བྱེད་ཀྱིན་ཡོད་པས་ ཚུལ་དེ་ནི་གསར - - - diff --git a/kona/doc/fmc_header.java b/kona/doc/fmc_header.java deleted file mode 100644 index df8f7801..00000000 --- a/kona/doc/fmc_header.java +++ /dev/null @@ -1,12 +0,0 @@ - -////////////// -// Name : {class name} -// Author : {your name} -// Rights : Copyright (c) 2012-$now By Feisty Meow Concerns, Ltd. -////////////// -// This script is free software; you can modify/redistribute it under the terms -// of the GNU General Public License. [ http://www.gnu.org/licenses/gpl.html ] -// Feel free to send updates to: [ fred@feistymeow.org ] -////////////// - - diff --git a/kona/doc/uva_header.java b/kona/doc/uva_header.java deleted file mode 100644 index 54b70eb7..00000000 --- a/kona/doc/uva_header.java +++ /dev/null @@ -1,12 +0,0 @@ - -////////////// -// Name : {class name} -// Author : {your name} -// Rights : Copyright (c) 2012-$now By University of Virginia -////////////// -// This file is free software; you can modify/redistribute it under the terms -// of the Apache License v2.0: http://www.apache.org/licenses/LICENSE-2.0 -// Feel free to send updates to: [ koeritz@virginia.edu ] -////////////// - - diff --git a/nucleus/library/basis/gnu_header.h b/nucleus/library/basis/gnu_header.h deleted file mode 100644 index 4c3eb2e1..00000000 --- a/nucleus/library/basis/gnu_header.h +++ /dev/null @@ -1,26 +0,0 @@ -#ifndef {NAME}_CLASS -#define {NAME}_CLASS - -////////////// -// Name : {class name} -// Author : {your name} -// Rights : Copyright (c) 2012-$now By Author -////////////// -// This file is free software; you can modify/redistribute it under the terms -// of the GNU General Public License. [ http://www.gnu.org/licenses/gpl.html ] -// Feel free to send updates to: [ fred@gruntose.com ] -////////////// - -//! brief description goes here. -/*! - detailed description goes here. -*/ - -////////////// - -// class definition goes here....... - -////////////// - -#endif - diff --git a/readme.txt b/readme.txt index d2dc6763..8f553742 100644 --- a/readme.txt +++ b/readme.txt @@ -15,7 +15,7 @@ database/ Some files considered critical to the operations of Feisty Meow Concerns Ltd. This includes the database of fortunes used by the Nechung Oracle Program. -docs/ +doc/ Assorted documentation files for Feisty Meow and a code-scanning documentation generator based on doxygen. diff --git a/scripts/core/shell_header.txt b/scripts/core/shell_header.txt deleted file mode 100644 index 739bb0b9..00000000 --- a/scripts/core/shell_header.txt +++ /dev/null @@ -1,13 +0,0 @@ -#!/bin/bash -#!/usr/bin/perl -#!/usr/bin/python -############## -# Name : {script name} -# Author : {your name} -# Rights : Copyright (C) 2012-$now by Feisty Meow Concerns, Ltd. -############## -# This script is free software; you can modify/redistribute it under the terms -# of the GNU General Public License. [ http://www.gnu.org/licenses/gpl.html ] -# Feel free to send updates to: [ fred@gruntose.com ] -############## -