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.