From 4c2325ee19dd37ffd05603147e7a8cf017e94974 Mon Sep 17 00:00:00 2001
From: philsquared <github@philnash.me>
Date: Tue, 8 Nov 2011 13:27:12 -0800
Subject: [PATCH] Created Supplying your own main() (markdown)

---
 Supplying-your-own-main().md | 78 ++++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)
 create mode 100644 Supplying-your-own-main().md

diff --git a/Supplying-your-own-main().md b/Supplying-your-own-main().md
new file mode 100644
index 0000000..4ba2d60
--- /dev/null
+++ b/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 );
+}
+```
\ No newline at end of file