= Add POSIX Method Signature Compliance Tests =

[[TOC(GCI/Coding/AddPOSIXMethodSignatureComplianceTests, depth=2)]]

== Directions for Students ==

**Prerequisite**: You '''must''' have completed the "Getting Started: Hello World" task or equivalently done the [wiki:GSoC/GettingStarted GSoC Getting Started Guide] before attempting this task.

===  Creating a Test  ===

To create a test, you'll need to be in the rtems/testsuite/psxtests/psxheader/@your_header@ directory. Note that the @your_header@ directory will be the name of the header file without the .h. For example, stdio.h related tests will be in psxtests/psxhdr/stdio and those for sys/mman.h are in sys/mman.

For the header file you have been given, you will be creating a simple test case that verifies that RTEMS matches the POSIX defined signature of the method as defined at XXX. Search for the header file you have been assigned and check every method that is in it. For each method, its specification page will have something like this (from time()):

{{{
}}}

The test for time() is in psxtests/psxhdr/time/time.c and (ignoring comments and boilerplate) is as follows:

{{{
#ifdef HAVE_CONFIG_H
#include "config.h"
#endif

#include <time.h>

int test( void );

int test( void )
{
  time_t    new_time;

  new_time = time( &new_time );

  return (new_time != -1);
}
}}}

Note that a variable of each time passed in and returned is declared. The POSIX standard told us that time() could be invoked by including only the <time.h> header file and this test verifies that RTEMS follows the standard.

Each header file has multiple methods. Each goes in a separate file. 

Use other existing tests as guides but note that some do not follow the proper Doxygen style expected now in RTEMS. Please use current style.

Also some use the RTEMS GPL v2 with exception license. Use the BSD style license found here: https://git.rtems.org/rtems-testing/tree/rtems-test-template/psxtest/init.c

===  Adding the Test to the Build System  ===

To add a test to the build system, you'll need to add it to psxtests/Makefile.am. Search for psxhdrs in the Makefile.am and then just add your new files to the list.

Then you'll need to "bootstrap" from the psxtests directory.

Now bootstrap it
{{{
 cd ~/rtems/testsuites/psxtests
 ~/rtems> ../../bootstrap
}}}

Now build...
{{{
 cd ../b-erc32
 ../rtems/configure --options --used --to --configure
}}}

Be sure to include --enable-tests on the configure command.

These tests are compile only and are not intended to be executed.

== Directions for Mentors == 

This should be evaluated as a normal code submission. You need to review and verify the tests compile warning free to ensure it is correct. These are compile-only tests. It should be based on the templates in rtems-testing. The student should provide a name and email for proper attribution. If you have write permission, commit it. Otherwise, send it to devel@rtems.org for another developer to commit with commentary indicating it is acceptable and from GCI.

Ensure the license and Doxygen file headers are correct.

Ensure it is using a BSD-0 style license.