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.