Adding upstream version 1:10.11.6.upstream/1%10.11.6

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

5 files changed, 490 insertions, 0 deletions

diff --git a/storage/maria/libmarias3/docs/contributors/coding_standards.rst b/storage/maria/libmarias3/docs/contributors/coding_standards.rst
new file mode 100644
index 00000000..a3242ffd
--- /dev/null
+++ b/storage/maria/libmarias3/docs/contributors/coding_standards.rst
@@ -0,0 +1,112 @@
+Coding Standard
+===============
+
+General
+-------
+
+We are aiming for a minimum of C99 support. A script in ``extra`` can be found called ``astyle.sh``. This uses the Linux tool `Artistic Style <http://astyle.sourceforge.net/>`_ to enforce coding standards.
+
+Coding Style
+------------
+
+Everyone has a preferred coding style, there is no real correct style.  What is important is that we stick to one style throughout the code.
+
+We should use a variant of the `Allman coding style <http://en.wikipedia.org/wiki/Indent_style#Allman_style>`_.  The variation is to use 2 spaces instead of tabs.  The exception to the rule is Makefiles where space indentation can break them.
+
+Allman style specifies that braces associated with a statement should be on the following line with the same indentation and the statements inside the braces are next level indented.  The closing braces are also on a new line at the same indentation as the original statement.
+
+For example:
+
+.. code-block:: cpp
+
+   while (x == y)
+   {
+     something();
+     somethingelse();
+   }
+   finalthing();
+
+
+Types
+-----
+
+Use C99 types (where possible), this will very much help us to find conversion bugs.  So:
+
+* Use bool, not my_bool.
+* Use true and false, not TRUE and FALSE (those macros need to die).
+* ulong → uint32_t
+* ulonglong uint64_t
+* long int → int32_t
+
+The keyword :c:type:`NULL` should always be used when referring to the pointer NULL
+
+Allocation
+----------
+
+For performance reasons we should try to limit the number of times we allocate and deallocate memory.  Do not do thousands of allocates and deallocates to save 32k of RAM.
+
+Naming style
+------------
+
+Variable names
+^^^^^^^^^^^^^^
+
+Variables should be verbosely names, no caps, underscores with spaces.  Do not just use ``i`` in for loops, again we have developers with bad eyes.
+
+Types
+^^^^^
+
+New types should use the ``_t`` postfix.  Private structs should be typedef'ed and also use this.
+
+Public Structs
+^^^^^^^^^^^^^^
+
+Public structs should be typedef'ed and use the ``_st`` postfix
+
+Conventions
+^^^^^^^^^^^
+
+* use *column* instead of *field*
+* use *schema* instead of *database*
+
+Include Files
+-------------
+
+Includes that will be installed need to be written like:
+
+.. code-block:: cpp
+
+   #include <drizzled/field/blob.h>
+
+
+The following should only be used in cases where we are to never install these libraries in the filesystem:
+
+.. code-block:: cpp
+
+   #include "item.h"
+
+Comments
+--------
+
+Where it is not obvious what is going on.  Hopefully most of the code will be self-commenting.
+
+All code should have license headers.
+
+Comment blocks should use the format:
+
+.. code-block:: cpp
+
+   /* Comment Block
+    * This is a multi-line comment block
+    */
+
+C99 style in-line and single line comments are allowed for small comments
+
+.. code-block:: cpp
+
+   // small comment
+
+Line lengths
+------------
+
+Whilst there is no hard limit on line lengths it is recommended that lines stay under 80 characters unless going above this increases readability of the code.
diff --git a/storage/maria/libmarias3/docs/contributors/docs.rst b/storage/maria/libmarias3/docs/contributors/docs.rst
new file mode 100644
index 00000000..47900a21
--- /dev/null
+++ b/storage/maria/libmarias3/docs/contributors/docs.rst
@@ -0,0 +1,45 @@
+Updating Documentation
+======================
+
+Overview
+--------
+
+This documentation is stored along with the source in the ``docs`` directory of the git tree and uses the `reStructuredText format <http://en.wikipedia.org/wiki/ReStructuredText>`_.
+
+We recommend reading this `reStructuredText Primer <http://sphinx-doc.org/rest.html>`_ before editing the docs for the first time.
+
+Compiling Docs
+--------------
+
+The docs are compiled using `Sphinx Python Documentation Generator <http://sphinx-doc.org/>`_.  The libMariaS3 build system already knows how to use this.  To compile the docs please follow theses steps:
+
+#. Install the ``python-sphinx`` package using your distribution's package manager
+
+#. Re-run bootstrap as follows so that it picks up that Sphinx is installed::
+
+      ./bootstrap.sh -m
+
+#. To compile in HTML format::
+
+      make html
+
+There will now be an HTML version of the docs in the ``/html`` directory of the source.
+
+Compiling PDF Docs
+------------------
+
+Sphinx required LaTeX to build PDF docs.  The following steps show you how to build PDF docs:
+
+#. Install ``python-sphinx`` as above
+
+#. Install the full *TeXLive* package.  In Fedora this is ``texlive-scheme-full`` and ``texlive-full`` in Ubuntu
+
+#. Re-run bootstrap as follows so that it picks up that Sphinx and LaTeX are installed::
+
+      ./bootstrap.sh -m
+
+#. To compile in PDF format::
+
+      make latexpdf
+
+The generated PDF will be in the ``/docs/latex/`` directory.
diff --git a/storage/maria/libmarias3/docs/contributors/github.rst b/storage/maria/libmarias3/docs/contributors/github.rst
new file mode 100644
index 00000000..11c91e64
--- /dev/null
+++ b/storage/maria/libmarias3/docs/contributors/github.rst
@@ -0,0 +1,113 @@
+Using GitHub
+============
+
+GitHub contributions typically work by creating a fork of the project on your user account, making a branch on that fork to work on and then filing a pull request to upstream your code.  This is how you would go about it.
+
+Forking
+-------
+
+Go to the `libMariaS3 GitHub page <https://github.com/mariadb-corporation/libmarias3>`_ and click the *Fork* button near the top.  Once you have forked you can get a local copy of this fork to work on (where *user* is your username):
+
+.. code-block:: bash
+
+   git clone https://github.com/user/libmarias3.git
+
+You then need to make your local clone aware of the upstream repository:
+
+.. code-block:: bash
+
+   cd libmarias3
+   git remote add upstream https://github.com/mariadb-corporation/libmarias3.git
+
+Branch
+------
+
+Before creating a branch to work on you should first make sure your local copy is up to date:
+
+.. code-block:: bash
+
+   git checkout master
+   git pull --ff-only upstream master
+   git push
+
+You can then create a branch from master to work on:
+
+.. code-block:: bash
+
+   git checkout -b a_new_feature
+
+Hack on code!
+-------------
+
+Hack away at your feature or bug.
+
+Test
+----
+
+Once your code is ready the test suite should be run locally:
+
+.. code-block:: bash
+
+   make
+   make check
+
+If there are documentation changes you should install ``python-sphinx`` and try to build the HTML version to run a syntax check:
+
+.. code-block:: bash
+
+   make html
+
+Commit and push
+---------------
+
+If you have never contributed to GitHub before then you need to setup git so that it knows you for the commit message:
+
+.. code-block:: bash
+
+   git config --global user.name "Real Name"
+   git config --global user.email "me@me.com"
+
+Make sure you use `git add` to add any new files to the repository and then commit:
+
+.. code-block:: bash
+
+   git commit -a
+
+Your editor will pop up to enter a commit messages above the comments.  The first line should be no more than 50 characters and be a subject of the commit.  The second line should be blank.  The third line onwards can contain details and these should be no more than 72 characters each.
+
+If your commit fixes an issue you can add the following (for issue #93)::
+
+   Fixes mariadb-corporation/libmarias3#93
+
+Once all your commits are done a quick rebase may be needed to make sure your changes will merge OK with what is in master:
+
+.. code-block:: bash
+
+   git fetch upstream
+   git rebase -i upstream/master
+
+This should bring up a commit-style message in the editor with *pick* as the first word.  Save this and the rebase will complete.  If the rebase tells you there is a conflict you will need to locate the problem using ``git diff``, fix it and do:
+
+.. code-block:: bash
+
+   git add <filename>
+   git rebase --continue
+
+If things look like they are going wrong you can undo the rebase using the following and can get in touch with us:
+
+.. code-block:: bash
+
+   git rebase --abort
+
+You should now be ready to push up to GitHub:
+
+.. code-block:: bash
+
+   git push --set-upstream origin a_new_feature
+
+If you go to your repository on GitHub's website you will an option to file a *Pull Request*.  Use this to submit a pull request upstream for your branch.
+
+Help
+----
+
+If you get stuck at any point feel free to reach out to us by filing an issue on Github.
diff --git a/storage/maria/libmarias3/docs/contributors/introduction.rst b/storage/maria/libmarias3/docs/contributors/introduction.rst
new file mode 100644
index 00000000..6e3d0164
--- /dev/null
+++ b/storage/maria/libmarias3/docs/contributors/introduction.rst
@@ -0,0 +1,58 @@
+Introduction to Contributing
+============================
+
+There are many ways to contribute to libMariaS3.  Simply using it and creating an issue report when you found a bug or have a suggestion is a great contribution.  Documentation and code contribituions are also greatly appreciated.
+
+Layout
+------
+
+The code for libMariaS3 in several parts:
+
++--------------------+-------------------------------+
+| Directory          | Contents                      |
++====================+===============================+
+| ``/src``           | The API source code           |
++--------------------+-------------------------------+
+| ``/libmarias3``    | The public API headers        |
++--------------------+-------------------------------+
+| ``/tests``         | Unit tests for the public API |
++--------------------+-------------------------------+
+
+In each case if any files are added or removed the ``include.am`` file in that directory will require updating to reflect the change.
+
+Submitting to Github
+--------------------
+
+The main hub for the code is `GitHub <https://github.com/>`_.  The main tree is the `libMariaS3 GitHub tree <https://github.com/mariadb-corporation/libmarias3>`_.  Anyone is welcome to submit pull requests or issues.  All requests will be considered and appropriate feedback given.
+
+Modifying the Build System
+--------------------------
+
+The build system is an m4 template system called `DDM4 <https://github.com/BrianAker/DDM4>`_.  If any changes are made to the scripts in ``m4`` directory the *serial* line will need incrementing in that file.  You should look for a line near the top that looks like:
+
+.. code-block:: makefile
+
+   #serial 7
+
+Shared Library Version
+^^^^^^^^^^^^^^^^^^^^^^
+
+If any of the source code has changed please see ``LIBMARIAS3_LIBRARY_VERSION`` in ``configure.ac``.  This gives rules on bumping the shared library versioning, not to be confused with the API public version which follows similar rules as described in the next section.
+
+API Version
+-----------
+
+API versioning is stored in the ``VERSION.txt`` file which is used by the build system to version the API and docs.  The versioning scheme follows the `Semantic Versioning Rules <http://semver.org/>`_.
+
+Function Visibility
+-------------------
+
+The code and build system only exposes public API functions as usable symbols in the finished binary.  This cuts down on binary size quite significantly and also discourages use of undocumented functionality that was not designed for public use.
+
+When adding a new API function to ``/libmarias3`` always add ``MS3_API`` on its own on the line above the function definition in the header.  This tells the build system this is an API function to be included.
+
+License Headers
+---------------
+
+Please make sure before committing that all new files have appropriate license headers in.  Only add to the copyright of older headers if you have made a significant contribution to that file (25 - 50 lines is typically classed as significant for Open Souce projects).
+
diff --git a/storage/maria/libmarias3/docs/contributors/test_cases.rst b/storage/maria/libmarias3/docs/contributors/test_cases.rst
new file mode 100644
index 00000000..f6796f04
--- /dev/null
+++ b/storage/maria/libmarias3/docs/contributors/test_cases.rst
@@ -0,0 +1,162 @@
+Writing Test Cases
+==================
+
+libMariaS3 uses DDM4's YATL library to create unit tests, this provides macros to test if the outcomes are as expected.
+
+Adding a Test Case
+------------------
+
+Test cases are basic C applications in the ``tests/`` directory.  To add a test case to the suite.  To add a test edit the ``include.am`` and add the following (replacing *mytest* with whatever the test is called):
+
+.. code-block:: makefile
+
+   t_mytest_SOURCES= tests/mytest.c
+   t_mytest_LDADD= src/libmarias3.la
+   check_PROGRAMS+= t/mytest
+   noinst_PROGRAMS+= t/mytest
+
+
+Using YATL
+----------
+
+YATL is needed to make sure conditions within the test program are met.  To include it in your test application, add the following:
+
+.. code-block:: c
+
+   #include <yatl/lite.h>
+
+A test skip can be added if certain conditions aren't met:
+
+.. code-block:: c
+
+   SKIP_IF_(!is_connected, "Cannot connected to a database server")
+
+There are many types of assert provided as can be seen in the next section, they can be used as follows:
+
+.. code-block:: c
+
+   ASSERT_EQ_(3, column, "Column count unexpected)
+   ASSERT_FALSE_(false_condition, "False condition is not false")
+   ASSERT_STREQ_("test", some_data, "Unexpected data")
+
+YATL Library
+------------
+
+Parameter Definitions
+^^^^^^^^^^^^^^^^^^^^^
+
+.. c:type:: __expression
+
+   An expression typically used in an ``if`` statement.
+
+.. c:type:: __expected
+
+   An expected variable or expression
+
+.. c:type:: __actual
+
+   The actual variable or expression
+
+.. c:type:: __expected_str
+
+   The expected string
+
+.. c:type:: __actual_str
+
+   The actual string to compare with
+
+.. c:type:: __length
+
+   The length of a string for comparison
+
+Function Definitions
+^^^^^^^^^^^^^^^^^^^^
+
+.. c:macro:: SKIP_IF(__expression)
+
+   Skips the test if the expression is true
+
+.. c:macro:: SKIP_IF_(__expression, ...)
+
+   Skips the test if the expression is true and uses a printf style format message
+
+.. c:macro:: ASSERT_TRUE(__expression)
+
+   Make sure the expression is true, test will fail if it is false
+
+.. c:macro:: ASSERT_FALSE(__expression)
+
+   Make sure the expression is false, test will fail if it is true
+
+.. c:macro:: ASSERT_FALSE_(__expression, ...)
+
+   Make sure the expression is false and use a printf style format message to fail if it is true.
+
+.. c:macro:: ASSERT_NULL_(__expression, ...)
+
+   Make sure the expression is :c:type:`NULL` and use a printf style format message to fail if it isn't.
+
+.. c:macro:: ASSERT_NOT_NULL(__expression)
+
+   Make sure the expression is not :c:type:`NULL`, test will fail if it is :c:type:`NULL`.
+
+.. c:macro:: ASSERT_NOT_NULL_(__expression, ...)
+
+   Make sure the expression is not :c:type:`NULL` and use a printf style format message to fail if it is.
+
+.. c:macro:: ASSERT_TRUE_(__expression, ...)
+
+   Make sure the expression is ``true`` and use a printf style format message to fail if it is not.
+
+.. c:macro:: ASSERT_EQ(__expected, __actual)
+
+   Make sure that one condition or variable matches another one.
+
+   .. note::
+      Not suitable for string matching
+
+.. c:macro:: ASSERT_EQ_(__expected, __actual, ...)
+
+   Make sure that one condition or variable matches another one and use a printf style format message to fail if the do not match.
+
+   .. note::
+      Not suitable for string matching
+
+.. c:macro:: ASSERT_NEQ(__expected, __actual)
+
+   Make sure that one condition or variable does not match another one.
+
+   .. note::
+      Not suitable for string matching
+
+.. c:macro:: ASSERT_NEQ_(__expected, __actual, ...)
+
+   Make sure that one condition or variable does not match another one and use a printf style format message to fail if they do match.
+
+   .. note::
+      Not suitable for string matching
+
+.. c:macro:: ASSERT_STREQ(__expected_str, __actual_str)
+
+   Compare one ``NUL`` terminated string with another one and fail if they do not match.
+
+.. c:macro:: ASSERT_STREQ_(__expected_str, __actual_str, ...)
+
+   Compare one ``NUL`` terminated string with another one and use a printf style format message to fail if they do not match.
+
+.. c:macro:: ASSERT_STREQL_(__expected_str, __actual_str, __length, ...)
+
+   Compare a string of :c:type:`__length` to another one and use a printf style format message to fail if they do not match.
+
+   .. note::
+      This is designed for use with non-NUL-terminated strings.
+
+.. c:macro:: ASSERT_STRNE(__expected_str, __actual_str)
+
+   Compare one ``NUL`` terminated string with another one and fail if they match.
+
+.. c:macro:: ASSERT_STRNE_(__expected_str, __actual_str, ...)
+
+   Compare one ``NUL`` terminated string with another one and use a printf style format message to fail if they match.
+
+