Merge branch 'wiki' of github.com:BillyDonahue/googlemock into wiki

DesignDoc.md

+This page discusses the design of new Google Mock features.
+
+
+
+# Macros for Defining Actions #
+
+## Problem ##
+
+Due to the lack of closures in C++, it currently requires some
+non-trivial effort to define a custom action in Google Mock.  For
+example, suppose you want to "increment the value pointed to by the
+second argument of the mock function and return it", you could write:
+
+```
+int IncrementArg1(Unused, int* p, Unused) {
+  return ++(*p);
+}
+
+... WillOnce(Invoke(IncrementArg1));
+```
+
+There are several things unsatisfactory about this approach:
+
+  * Even though the action only cares about the second argument of the mock function, its definition needs to list other arguments as dummies.  This is tedious.
+  * The defined action is usable only in mock functions that takes exactly 3 arguments - an unnecessary restriction.
+  * To use the action, one has to say `Invoke(IncrementArg1)`, which isn't as nice as `IncrementArg1()`.
+
+The latter two problems can be overcome using `MakePolymorphicAction()`,
+but it requires much more boilerplate code:
+
+```
+class IncrementArg1Action {
+ public:
+  template <typename Result, typename ArgumentTuple>
+  Result Perform(const ArgumentTuple& args) const {
+    return ++(*tr1::get<1>(args));
+  }
+};
+
+PolymorphicAction<IncrementArg1Action> IncrementArg1() {
+  return MakePolymorphicAction(IncrementArg1Action());
+}
+
+... WillOnce(IncrementArg1());
+```
+
+Our goal is to allow defining custom actions with the least amount of
+boiler-plate C++ requires.
+
+## Solution ##
+
+We propose to introduce a new macro:
+```
+ACTION(name) { statements; }
+```
+
+Using this in a namespace scope will define an action with the given
+name that executes the statements.  Inside the statements, you can
+refer to the K-th (0-based) argument of the mock function as `argK`.
+For example:
+```
+ACTION(IncrementArg1) { return ++(*arg1); }
+```
+allows you to write
+```
+... WillOnce(IncrementArg1());
+```
+
+Note that you don't need to specify the types of the mock function
+arguments, as brevity is a top design goal here.  Rest assured that
+your code is still type-safe though: you'll get a compiler error if
+`*arg1` doesn't support the `++` operator, or if the type of
+`++(*arg1)` isn't compatible with the mock function's return type.
+
+Another example:
+```
+ACTION(Foo) {
+  (*arg2)(5);
+  Blah();
+  *arg1 = 0;
+  return arg0;
+}
+```
+defines an action `Foo()` that invokes argument #2 (a function pointer)
+with 5, calls function `Blah()`, sets the value pointed to by argument
+#1 to 0, and returns argument #0.
+
+For more convenience and flexibility, you can also use the following
+pre-defined symbols in the body of `ACTION`:
+
+| `argK_type` | The type of the K-th (0-based) argument of the mock function |
+|:------------|:-------------------------------------------------------------|
+| `args`      | All arguments of the mock function as a tuple                |
+| `args_type` | The type of all arguments of the mock function as a tuple    |
+| `return_type` | The return type of the mock function                         |
+| `function_type` | The type of the mock function                                |
+
+For example, when using an `ACTION` as a stub action for mock function:
+```
+int DoSomething(bool flag, int* ptr);
+```
+we have:
+| **Pre-defined Symbol** | **Is Bound To** |
+|:-----------------------|:----------------|
+| `arg0`                 | the value of `flag` |
+| `arg0_type`            | the type `bool` |
+| `arg1`                 | the value of `ptr` |
+| `arg1_type`            | the type `int*` |
+| `args`                 | the tuple `(flag, ptr)` |
+| `args_type`            | the type `std::tr1::tuple<bool, int*>` |
+| `return_type`          | the type `int`  |
+| `function_type`        | the type `int(bool, int*)` |
+
+## Parameterized actions ##
+
+Sometimes you'll want to parameterize the action.   For that we propose
+another macro
+```
+ACTION_P(name, param) { statements; }
+```
+
+For example,
+```
+ACTION_P(Add, n) { return arg0 + n; }
+```
+will allow you to write
+```
+// Returns argument #0 + 5.
+... WillOnce(Add(5));
+```
+
+For convenience, we use the term _arguments_ for the values used to
+invoke the mock function, and the term _parameters_ for the values
+used to instantiate an action.
+
+Note that you don't need to provide the type of the parameter either.
+Suppose the parameter is named `param`, you can also use the
+Google-Mock-defined symbol `param_type` to refer to the type of the
+parameter as inferred by the compiler.
+
+We will also provide `ACTION_P2`, `ACTION_P3`, and etc to support
+multi-parameter actions.  For example,
+```
+ACTION_P2(ReturnDistanceTo, x, y) {
+  double dx = arg0 - x;
+  double dy = arg1 - y;
+  return sqrt(dx*dx + dy*dy);
+}
+```
+lets you write
+```
+... WillOnce(ReturnDistanceTo(5.0, 26.5));
+```
+
+You can view `ACTION` as a degenerated parameterized action where the
+number of parameters is 0.
+
+## Advanced Usages ##
+
+### Overloading Actions ###
+
+You can easily define actions overloaded on the number of parameters:
+```
+ACTION_P(Plus, a) { ... }
+ACTION_P2(Plus, a, b) { ... }
+```
+
+### Restricting the Type of an Argument or Parameter ###
+
+For maximum brevity and reusability, the `ACTION*` macros don't let
+you specify the types of the mock function arguments and the action
+parameters.  Instead, we let the compiler infer the types for us.
+
+Sometimes, however, we may want to be more explicit about the types.
+There are several tricks to do that.  For example:
+```
+ACTION(Foo) {
+  // Makes sure arg0 can be converted to int.
+  int n = arg0;
+  ... use n instead of arg0 here ...
+}
+
+ACTION_P(Bar, param) {
+  // Makes sure the type of arg1 is const char*.
+  ::testing::StaticAssertTypeEq<const char*, arg1_type>();
+
+  // Makes sure param can be converted to bool.
+  bool flag = param;
+}
+```
+where `StaticAssertTypeEq` is a compile-time assertion we plan to add to
+Google Test (the name is chosen to match `static_assert` in C++0x).
+
+### Using the ACTION Object's Type ###
+
+If you are writing a function that returns an `ACTION` object, you'll
+need to know its type.  The type depends on the macro used to define
+the action and the parameter types.  The rule is relatively simple:
+| **Given Definition** | **Expression** | **Has Type** |
+|:---------------------|:---------------|:-------------|
+| `ACTION(Foo)`        | `Foo()`        | `FooAction`  |
+| `ACTION_P(Bar, param)` | `Bar(int_value)` | `BarActionP<int>` |
+| `ACTION_P2(Baz, p1, p2)` | `Baz(bool_value, int_value)` | `BazActionP2<bool, int>` |
+| ...                  | ...            | ...          |
+
+Note that we have to pick different suffixes (`Action`, `ActionP`,
+`ActionP2`, and etc) for actions with different numbers of parameters,
+or the action definitions cannot be overloaded on the number of
+parameters.
+
+## When to Use ##
+
+While the new macros are very convenient, please also consider other
+means of implementing actions (e.g. via `ActionInterface` or
+`MakePolymorphicAction()`), especially if you need to use the defined
+action a lot.  While the other approaches require more work, they give
+you more control on the types of the mock function arguments and the
+action parameters, which in general leads to better compiler error
+messages that pay off in the long run.  They also allow overloading
+actions based on parameter types, as opposed to just the number of
+parameters.
+
+## Related Work ##
+
+As you may have realized, the `ACTION*` macros resemble closures (also
+known as lambda expressions or anonymous functions).  Indeed, both of
+them seek to lower the syntactic overhead for defining a function.
+
+C++0x will support lambdas, but they are not part of C++ right now.
+Some non-standard libraries (most notably BLL or Boost Lambda Library)
+try to alleviate this problem.  However, they are not a good choice
+for defining actions as:
+
+  * They are non-standard and not widely installed.  Google Mock only depends on standard libraries and `tr1::tuple`, which is part of the new C++ standard and comes with gcc 4+.  We want to keep it that way.
+  * They are not trivial to learn.
+  * They will become obsolete when C++0x's lambda feature is widely supported.  We don't want to make our users use a dying library.
+  * Since they are based on operators, they are rather ad hoc: you cannot use statements, and you cannot pass the lambda arguments to a function, for example.
+  * They have subtle semantics that easily confuses new users.  For example, in expression `_1++ + foo++`, `foo` will be incremented only once where the expression is evaluated, while `_1` will be incremented every time the unnamed function is invoked.  This is far from intuitive.
+
+`ACTION*` avoid all these problems.
+
+## Future Improvements ##
+
+There may be a need for composing `ACTION*` definitions (i.e. invoking
+another `ACTION` inside the definition of one `ACTION*`).  We are not
+sure we want it yet, as one can get a similar effect by putting
+`ACTION` definitions in function templates and composing the function
+templates.  We'll revisit this based on user feedback.
+
+The reason we don't allow `ACTION*()` inside a function body is that
+the current C++ standard doesn't allow function-local types to be used
+to instantiate templates.  The upcoming C++0x standard will lift this
+restriction.  Once this feature is widely supported by compilers, we
+can revisit the implementation and add support for using `ACTION*()`
+inside a function.
+
+C++0x will also support lambda expressions.  When they become
+available, we may want to support using lambdas as actions.
+
+# Macros for Defining Matchers #
+
+Once the macros for defining actions are implemented, we plan to do
+the same for matchers:
+
+```
+MATCHER(name) { statements; }
+```
+
+where you can refer to the value being matched as `arg`.  For example,
+given:
+
+```
+MATCHER(IsPositive) { return arg > 0; }
+```
+
+you can use `IsPositive()` as a matcher that matches a value iff it is
+greater than 0.
+
+We will also add `MATCHER_P`, `MATCHER_P2`, and etc for parameterized
+matchers.
\ No newline at end of file

DevGuide.md

+
+
+If you are interested in understanding the internals of Google Mock,
+building from source, or contributing ideas or modifications to the
+project, then this document is for you.
+
+# Introduction #
+
+First, let's give you some background of the project.
+
+## Licensing ##
+
+All Google Mock source and pre-built packages are provided under the [New BSD License](http://www.opensource.org/licenses/bsd-license.php).
+
+## The Google Mock Community ##
+
+The Google Mock community exists primarily through the [discussion group](http://groups.google.com/group/googlemock), the
+[issue tracker](http://code.google.com/p/googlemock/issues/list) and, to a lesser extent, the [source control repository](http://code.google.com/p/googlemock/source/checkout). You are definitely encouraged to contribute to the
+discussion and you can also help us to keep the effectiveness of the
+group high by following and promoting the guidelines listed here.
+
+### Please Be Friendly ###
+
+Showing courtesy and respect to others is a vital part of the Google
+culture, and we strongly encourage everyone participating in Google
+Mock development to join us in accepting nothing less. Of course,
+being courteous is not the same as failing to constructively disagree
+with each other, but it does mean that we should be respectful of each
+other when enumerating the 42 technical reasons that a particular
+proposal may not be the best choice. There's never a reason to be
+antagonistic or dismissive toward anyone who is sincerely trying to
+contribute to a discussion.
+
+Sure, C++ testing is serious business and all that, but it's also
+a lot of fun. Let's keep it that way. Let's strive to be one of the
+friendliest communities in all of open source.
+
+### Where to Discuss Google Mock ###
+
+As always, discuss Google Mock in the official [Google C++ Mocking Framework discussion group](http://groups.google.com/group/googlemock).  You don't have to actually submit
+code in order to sign up. Your participation itself is a valuable
+contribution.
+
+# Working with the Code #
+
+If you want to get your hands dirty with the code inside Google Mock,
+this is the section for you.
+
+## Checking Out the Source from Subversion ##
+
+Checking out the Google Mock source is most useful if you plan to
+tweak it yourself.  You check out the source for Google Mock using a
+[Subversion](http://subversion.tigris.org/) client as you would for any
+other project hosted on Google Code.  Please see the instruction on
+the [source code access page](http://code.google.com/p/googlemock/source/checkout) for how to do it.
+
+## Compiling from Source ##
+
+Once you check out the code, you can find instructions on how to
+compile it in the [README](http://code.google.com/p/googlemock/source/browse/trunk/README) file.
+
+## Testing ##
+
+A mocking framework is of no good if itself is not thoroughly tested.
+Tests should be written for any new code, and changes should be
+verified to not break existing tests before they are submitted for
+review. To perform the tests, follow the instructions in [README](http://code.google.com/p/googlemock/source/browse/trunk/README) and
+verify that there are no failures.
+
+# Contributing Code #
+
+We are excited that Google Mock is now open source, and hope to get
+great patches from the community. Before you fire up your favorite IDE
+and begin hammering away at that new feature, though, please take the
+time to read this section and understand the process. While it seems
+rigorous, we want to keep a high standard of quality in the code
+base.
+
+## Contributor License Agreements ##
+
+You must sign a Contributor License Agreement (CLA) before we can
+accept any code.  The CLA protects you and us.
+
+  * If you are an individual writing original source code and you're sure you own the intellectual property, then you'll need to sign an [individual CLA](http://code.google.com/legal/individual-cla-v1.0.html).
+  * If you work for a company that wants to allow you to contribute your work to Google Mock, then you'll need to sign a [corporate CLA](http://code.google.com/legal/corporate-cla-v1.0.html).
+
+Follow either of the two links above to access the appropriate CLA and
+instructions for how to sign and return it.
+
+## Coding Style ##
+
+To keep the source consistent, readable, diffable and easy to merge,
+we use a fairly rigid coding style, as defined by the [google-styleguide](http://code.google.com/p/google-styleguide/) project.  All patches will be expected
+to conform to the style outlined [here](http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml).
+
+## Submitting Patches ##
+
+Please do submit code. Here's what you need to do:
+
+  1. Normally you should make your change against the SVN trunk instead of a branch or a tag, as the latter two are for release control and should be treated mostly as read-only.
+  1. Decide which code you want to submit. A submission should be a set of changes that addresses one issue in the [Google Mock issue tracker](http://code.google.com/p/googlemock/issues/list). Please don't mix more than one logical change per submittal, because it makes the history hard to follow. If you want to make a change that doesn't have a corresponding issue in the issue tracker, please create one.
+  1. Also, coordinate with team members that are listed on the issue in question. This ensures that work isn't being duplicated and communicating your plan early also generally leads to better patches.
+  1. Ensure that your code adheres to the [Google Mock source code style](#Coding_Style.md).
+  1. Ensure that there are unit tests for your code.
+  1. Sign a Contributor License Agreement.
+  1. Create a patch file using `svn diff`.
+  1. We use [Rietveld](http://codereview.appspot.com/) to do web-based code reviews.  You can read about the tool [here](http://code.google.com/p/rietveld/wiki/CodeReviewHelp).  When you are ready, upload your patch via Rietveld and notify `googlemock@googlegroups.com` to review it.  There are several ways to upload the patch.  We recommend using the [upload\_gmock.py](http://code.google.com/p/googlemock/source/browse/trunk/scripts/upload_gmock.py) script, which you can find in the `scripts/` folder in the SVN trunk.
+
+## Google Mock Committers ##
+
+The current members of the Google Mock engineering team are the only
+committers at present. In the great tradition of eating one's own
+dogfood, we will be requiring each new Google Mock engineering team
+member to earn the right to become a committer by following the
+procedures in this document, writing consistently great code, and
+demonstrating repeatedly that he or she truly gets the zen of Google
+Mock.
+
+# Release Process #
+
+We follow the typical release process for Subversion-based projects:
+
+  1. A release branch named `release-X.Y` is created.
+  1. Bugs are fixed and features are added in trunk; those individual patches are merged into the release branch until it's stable.
+  1. An individual point release (the `Z` in `X.Y.Z`) is made by creating a tag from the branch.
+  1. Repeat steps 2 and 3 throughout one release cycle (as determined by features or time).
+  1. Go back to step 1 to create another release branch and so on.
+
+
+---
+
+This page is based on the [Making GWT Better](http://code.google.com/webtoolkit/makinggwtbetter.html) guide from the [Google Web Toolkit](http://code.google.com/webtoolkit/) project.  Except as otherwise [noted](http://code.google.com/policies.html#restrictions), the content of this page is licensed under the [Creative Commons Attribution 2.5 License](http://creativecommons.org/licenses/by/2.5/).
\ No newline at end of file

Documentation.md

+This page lists all documentation wiki pages for Google Mock **(the SVN trunk version)**
+- **if you use a released version of Google Mock, please read the documentation for that specific version instead.**
+
+  * [ForDummies](ForDummies.md) -- start here if you are new to Google Mock.
+  * [CheatSheet](CheatSheet.md) -- a quick reference.
+  * [CookBook](CookBook.md) -- recipes for doing various tasks using Google Mock.
+  * [FrequentlyAskedQuestions](FrequentlyAskedQuestions.md) -- check here before asking a question on the mailing list.
+
+To contribute code to Google Mock, read:
+
+  * [DevGuide](DevGuide.md) -- read this _before_ writing your first patch.
+  * [Pump Manual](http://code.google.com/p/googletest/wiki/PumpManual) -- how we generate some of Google Mock's source files.
\ No newline at end of file

KnownIssues.md

+As any non-trivial software system, Google Mock has some known limitations and problems.  We are working on improving it, and welcome your help!  The follow is a list of issues we know about.
+
+
+
+## README contains outdated information on Google Mock's compatibility with other testing frameworks ##
+
+The `README` file in release 1.1.0 still says that Google Mock only works with Google Test.  Actually, you can configure Google Mock to work with any testing framework you choose.
+
+## Tests failing on machines using Power PC CPUs (e.g. some Macs) ##
+
+`gmock_output_test` and `gmock-printers_test` are known to fail with Power PC CPUs.  This is due to portability issues with these tests, and is not an indication of problems in Google Mock itself.  You can safely ignore them.
+
+## Failed to resolve libgtest.so.0 in tests when built against installed Google Test ##
+
+This only applies if you manually built and installed Google Test, and then built a Google Mock against it (either explicitly, or because gtest-config was in your path post-install). In this situation, Libtool has a known issue with certain systems' ldconfig setup:
+
+http://article.gmane.org/gmane.comp.sysutils.automake.general/9025
+
+This requires a manual run of "sudo ldconfig" after the "sudo make install" for Google Test before any binaries which link against it can be executed. This isn't a bug in our install, but we should at least have documented it or hacked a work-around into our install. We should have one of these solutions in our next release.
\ No newline at end of file

ProjectHome.md

+
+
+Please follow **Google Mock** to its new home on **Git Hub**!
+> http://github.com/google/googlemock
+
+
+---
+
+
+Welcome to **Google C++ Mocking Framework**!
+
+Inspired by [jMock](http://www.jmock.org/), [EasyMock](http://www.easymock.org/), and [Hamcrest](http://code.google.com/p/hamcrest/), and
+designed with C++'s specifics in mind, Google C++ Mocking Framework
+(or **Google Mock** for short) is a library for writing and using C++
+mock classes.  Google Mock:
+
+  * lets you create mock classes trivially using simple macros,
+  * supports a rich set of matchers and actions,
+  * handles unordered, partially ordered, or completely ordered expectations,
+  * is extensible by users, and
+  * works on Linux, Mac OS X, Windows, Windows Mobile, minGW, and Symbian.
+
+We hope you find it useful!
+
+## Who are using Google Mock? ##
+
+We have enjoyed using Google Mock in many projects at Google.  Outside of Google, the most notable client is probably the [Chromium projects](http://www.chromium.org/) (behind the Chrome browser and Chrome OS).  If you know of a project that's using Google Mock and want it to be listed here, please let
+`googlemock@googlegroups.com` know.
+
+
+## System Requirements ##
+
+Google Mock is not a testing framework itself.  Instead, it needs a
+testing framework for writing tests.  Google Mock works seamlessly
+with [Google Test](http://code.google.com/p/googletest/).  It comes
+with a copy of Google Test bundled.  Starting with version 1.1.0,
+you can also use it with [any C++ testing framework of your choice](ForDummies#Using_Google_Mock_with_Any_Testing_Framework.md).
+
+Google Mock has been tested with **gcc 4.0+** and **Microsoft Visual C++ 8.0 SP1**.  Users
+reported that it also works with **gcc 3.4**, **Microsoft Visual C++ 7.1**, and **Cygwin**, although we haven't tested it there ourselves.
+
+## Getting Started ##
+
+If you are new to the project, we suggest to read the user
+documentation in the following order:
+
+  * Learn the [basics](http://code.google.com/p/googletest/wiki/Primer) of Google Test, if you choose to use Google Mock with it (recommended).
+  * Read [Google Mock for Dummies](ForDummies.md).
+  * Read the instructions on how to [build Google Mock](http://code.google.com/p/googlemock/source/browse/trunk/README).
+
+You can also watch Zhanyong's [talk](http://www.youtube.com/watch?v=sYpCyLI47rM) on Google Mock's usage and implementation.
+
+Once you understand the basics, check out the rest of the docs:
+
+  * CheatSheet - all the commonly used stuff at a glance.
+  * CookBook - recipes for getting things done, including advanced techniques.
+
+If you need help, please check the KnownIssues and FrequentlyAskedQuestions before
+posting a question on the [googlemock](http://groups.google.com/group/googlemock)
+discussion group.
+
+We'd love to have your help!  Please
+read the DevGuide if you are willing to contribute to the development.
+
+Happy mocking!
\ No newline at end of file

V1_5_Documentation.md

+This page lists all documentation wiki pages for Google Mock **version 1.5.0** -- **if you use a different version of Google Mock, please read the documentation for that specific version instead.**
+
+  * [ForDummies](V1_5_ForDummies.md) -- start here if you are new to Google Mock.
+  * [CheatSheet](V1_5_CheatSheet.md) -- a quick reference.
+  * [CookBook](V1_5_CookBook.md) -- recipes for doing various tasks using Google Mock.
+  * [FrequentlyAskedQuestions](V1_5_FrequentlyAskedQuestions.md) -- check here before asking a question on the mailing list.
+
+To contribute code to Google Mock, read:
+
+  * DevGuide -- read this _before_ writing your first patch.
+  * [Pump Manual](http://code.google.com/p/googletest/wiki/PumpManual) -- how we generate some of Google Mock's source files.
\ No newline at end of file

V1_6_Documentation.md

+This page lists all documentation wiki pages for Google Mock **1.6**
+- **if you use a released version of Google Mock, please read the documentation for that specific version instead.**
+
+  * [ForDummies](V1_6_ForDummies.md) -- start here if you are new to Google Mock.
+  * [CheatSheet](V1_6_CheatSheet.md) -- a quick reference.
+  * [CookBook](V1_6_CookBook.md) -- recipes for doing various tasks using Google Mock.
+  * [FrequentlyAskedQuestions](V1_6_FrequentlyAskedQuestions.md) -- check here before asking a question on the mailing list.
+
+To contribute code to Google Mock, read:
+
+  * [DevGuide](DevGuide.md) -- read this _before_ writing your first patch.
+  * [Pump Manual](http://code.google.com/p/googletest/wiki/V1_6_PumpManual) -- how we generate some of Google Mock's source files.
\ No newline at end of file