Created Supplying your own main() (markdown)

Supplying-your-own-main().md

@@ -0,0 +1,78 @@
+The easiest way to use Catch is to let it supply main() for you and handle configuring itself from the command line.
+
+This is achieved by #defining CATCH_CONFIG_MAIN before the #include for catch.hpp in exactly one source file.
+
+Sometimes, though, you'd like to write your own version of main(). You can do this by #defining CATCH_CONFIG_RUNNER instead.
+
+Catch then supports this in three ways:
+
+1. Forward onto Catch's main but write code before and/ or after for global setup/ cleanup purposes. Catch will still configure itself from the command line as before.
+2. As above but your can programatically set parts, or all, of Catch's configuration.
+3. Set configuration and run specific tests directly from your own code.
+
+Let's look at each of these in a little more detail.
+
+# Wrapping Catch's main()
+
+```c++
+#define CATCH_CONFIG_RUNNER
+#include "catch.hpp"
+
+int main (int argc, char* const argv[])
+{
+  // global setup...
+
+  int result = Catch::Main( argc, argv );
+
+  // global clean-up...
+
+  return result;
+}
+```
+
+# Configuring Catch
+
+```c++
+#define CATCH_CONFIG_RUNNER
+#include "catch.hpp"
+
+int main (int argc, char* const argv[])
+{
+  // Create a default config object
+  Catch::Config config;
+
+  Configure Catch to send all its output to a stringstream
+  std::ostringstream oss;
+  config.setStreamBuf( oss.rdbuf() );
+
+  // Forward on to Catch's main, but using our custom config.
+  // Catch will still parse the command line and set the config
+  // object up further
+  int result = Catch::Main( argc, argv, config );
+
+  std::cout << oss.str() << std::endl;
+
+  return result;
+}
+```
+
+# Fully configured
+
+```c++
+#define CATCH_CONFIG_RUNNER
+#include "catch.hpp"
+
+int main (int argc, char* const argv[])
+{
+  // Create a default config object
+  Catch::Config config;
+
+  // Configure Catch to run all tests starting with "mytests"
+  config.addTestSpec( "mytests/*" );
+
+  // Forward on to Catch's main using our custom config.
+  // This overload doesn't take command line arguments
+  // So the config object must be fully set up
+  return Catch::Main( config );
+}
+```