CONTRIBUTING

CONTRIBUTING
============

This file is intended to help those interested in contributing to the
memkind library.


COMMUNICATION
=============

Please participate in the memkind mailing list:

    https://lists.01.org/mailman/listinfo/memkind

There is also the option of opening an issue through github:

    https://github.com/memkind/memkind/issues

The mailing list is intended for discussion and the issues are useful
for tracking progress on tasks.  The TODO file lists out a number of
topics, and in order to prioritize one of them please open a github
issue with a related subject.


TESTING
=======

The tests require a Linux kernel newer than 3.11 (the details are
documented in the memkind README), and the reservation of 3000 huge
pages.  The huge pages can be reserved with the following command:

    $ sudo echo 3000 > /proc/sys/vm/nr_hugepages

Only in the case where gigabyte pages have been reserved will the
tests associated with gigabyte pages be executed.  Reserving gigabyte
pages may require a modification to the kernel command line unless the
kernel is quite recent.

To test memkind simply execute the "make check" target after building.
This target calls memkind/test/test.sh with parameters
depending on the environment.

Most of the tests are written within the gtest framework, however, as
part of testing the example programs are also executed and the return
code of the executable determines pass or fail.  The autotools test
infrastructure is used as a high level executor, but it does not track
individual tests.  The consequence of this is that the autotools
output records only one high level test which passes in the case where
every underlying test was successful and fails if any underlying test
fails.  The individual test results are recorded in the directory
called "gtest_output." Here you will find the log of the tests in
gtest_output/test.out and a set of junit style xml results: one for
each test.  Note that a side effect of having only one autotools test
is that autotools parallel testing is disabled.  We have
multi-threaded tests that use the OpenMP run-time which enables more
purposeful and deterministic testing of threading issues.  Note that
the OpenMP run-time is only required for testing, it is not used by
the memkind library internally.


CODING STYLE
============

Before submitting a patch for inclusion, please run the modified
source code files through astyle with the following options

    $ astyle --style=linux --indent=spaces=4 -S --max-continuation-indent=80 \
             --max-code-length=80 --break-after-logical --indent-namespaces -z2 \
             --align-pointer=name

More information about astyle can be found here:

    http://astyle.sourceforge.net/

In C, source code constants are in all caps and everything else is in
all lower case.  Underscores are used to separate words within a
symbol name. No camel case shall be used in C code.  The test code is
largely written in C++.  Here camel-case should be used for class
names and should always have a capitalized first letter.  Other
symbols in C++ should generally follow the C style.

Most symbols with global scope shall be prefixed with "memkind_" or
"hbw_" depending on which interface they are a part of.

Any global variable shall have _g appended to the variable name and in
most cases shall be statically scoped within a single compilation
unit.  The exception to that rule are static memory kinds that are
declared as extern within the associated interface header and are
constant after initialization.  Global variables should be used in a
very narrow set of circumstances and in most cases modifications
should be guarded with pthread_once(3).

Functions not used outside of the compilation unit shall be declared
as static.  All functions which are not declared as static shall be
documented in a man page and have an associated interface header file.

Preprocessor mark-up is discouraged when other options are possible.
Please use enum in place of #define when value control at configure or
build time is not required.


TESTS
=====

The current state of the tests is not nearly as well organized as it
could be.  That being said, it is quite simple to add a new test.
Most C++ files in the test directory are associated with a single
gtest testing::Test class.  These classes usually have several
associated test fixtures in the same file.  If a new test can be added
as a fixture to an existing class, simply add the fixture to the file
and the test will be incorporated into the test infrastructure.
If a new class is required, create a new file and add it to the list
of "test_all_tests_SOURCES" in memkind/test/Makfile.mk and it will
be incorporated into the test infrastructure.

There are a few files which define classes which are not google test
classes.  These are check.cpp, trial_generator.cpp and main.cpp.  The
check.cpp file defines a class Check that can be used to validate
fundamental memkind features like NUMA node location, and page size.
The trial_generator.cpp file is used to abstract a sequence of
allocation and deallocation calls while performing checks on the
results of each call; this can be used to apply similar tests to all
of the different allocation APIs.  The main.cpp file is a simple
wrapper around testing::InitGoogleTest and RUN_ALL_TESTS().


SUBMITTING A PATCH
==================

Please be sure that all tests pass before submission and that the
style conforms to the specifications given here.  If a new feature is
implemented in the patch, please also include unit tests and an
example which exercises this feature.  Once these requirements have
been met, please submit a pull request through github.