bgneal@0: fructose_gen.py
bgneal@0: ===============
bgneal@0: 
bgneal@0: Quick Start
bgneal@0: -----------
bgneal@0: 
bgneal@0: `fructose_gen.py` is a Python script for auto-generatng the `main()` function
bgneal@0: for the C++ testing framework [Fructose][1].
bgneal@0: 
bgneal@0: Sample usage:
bgneal@0: 
bgneal@0:     $ python fructose_gen.py [options] test1.h test2.h ... testN.h > main.cpp
bgneal@0: 
bgneal@0: In this example, `fructose_gen.py` will read the Fructose test files `test1.h`
bgneal@0: through `testN.h` and produce on standard output C++ code with a generated
bgneal@0: `main()` function. This auto-generated code will instantiate all the test
bgneal@0: instances, register the appropriate tests with each instance, and then execute
bgneal@0: each test in turn.
bgneal@0: 
bgneal@0: To see usage information and a list of options:
bgneal@0: 
bgneal@0:     $ python fructose_gen.py --help
bgneal@0: 
bgneal@0: 
bgneal@0: Code Generation Styles
bgneal@0: ----------------------
bgneal@0: 
bgneal@0: `fructose_gen.py` supports two styles of code generation, described below.
bgneal@0: 
bgneal@0: ### xUnit Style ###
bgneal@0: 
bgneal@0: The default style is xUnit style. In this form, `fructose_gen.py` will scan
bgneal@0: C++ code looking for classes or structs that inherit from `fructose::test_base<>`.
bgneal@0: Inside those classes or structs, member functions that match the following
bgneal@0: pattern are assumed to be test functions:
bgneal@0: 
bgneal@0:       void testXXXX(const std::string&)
bgneal@0: 
bgneal@0: Upon finding such a function, `fructose_gen.py` will register that member
bgneal@0: function as a test with the name "testXXXX". 
bgneal@0: 
bgneal@0: 
bgneal@0: ### Generator Style ###
bgneal@0: 
bgneal@0: To remain backward compatible with the `generator` program that ships with
bgneal@0: Fructose, invoke `fructose_gen.py` with a `-g` or `--generator` option flag.
bgneal@0: 
bgneal@0: In this style, `fructose_gen.py` will scan files for the `FRUCTOSE_CLASS`,
bgneal@0: `FRUCTOSE_STRUCT` and `FRUCTOSE_TEST` macros. See the Fructose documentation
bgneal@0: for more information.
bgneal@0: 
bgneal@0: 
bgneal@0: Caveats
bgneal@0: -------
bgneal@0: 
bgneal@0: `fructose_gen.py` is not a true C++ code parser, and in fact is quite simple
bgneal@0: in how it operates. This is sufficient for most cases, but please be aware of
bgneal@0: the following limitations.
bgneal@0: 
bgneal@1: 1.  Ensure your class (or struct) definition is all on one line:
bgneal@0: 
bgneal@0:          class my_unit_test : public fructose::test_base<my_unit_test>
bgneal@0: 
bgneal@1:     If you split the above across multiple lines `fructose_gen.py` will not
bgneal@1:     recognize your class and will not generate a test instance for it.
bgneal@0: 
bgneal@1: 2.  `fructose_gen.py` does not understand C-style comments or the preprocessor.
bgneal@1:     To comment out a test, you can either use C++ comments, or change the function
bgneal@1:     name slightly to ensure it won't be recognized. Examples:
bgneal@0: 
bgneal@0:           /*
bgneal@0:           ** void test_is_sorted(const std::string& name)  // this won't work
bgneal@0:           */
bgneal@0: 
bgneal@0:           #if 0
bgneal@0:           void test_is_sorted(const std::string& name)   // this won't work
bgneal@0:           #endif
bgneal@0: 
bgneal@0:           void not_a_test_is_sorted(const std::string& name) // this works
bgneal@0:           // void test_is_sorted(const std::string& name)    // this works
bgneal@0:           // FRUCTOSE_TEST(is_sorted)                        // this works
bgneal@0: 
bgneal@1:     The above also applies to commenting out test classes.
bgneal@0: 
bgneal@0: 
bgneal@0: Support
bgneal@0: -------
bgneal@0: See the [fructose_gen support site][2] hosted at [bitbucket.org][3].
bgneal@0: 
bgneal@0: 
bgneal@0: [1]: http://fructose.sourceforge.net/
bgneal@0: [2]: https://bitbucket.org/bgneal/fructose_gen
bgneal@0: [3]: https://bitbucket.org