[LTP] [PATCH 1/2] doc: Remove Style Guide

[LTP] [PATCH 1/2] doc: Remove Style Guide

[Petr Vorel]

it was outdated and partly redundant with test-writing-guidelines.txt.

Acked-by: Li Wang <liwang@redhat.com>
Acked-by: Jan Stancek <jstancek@redhat.com>
Signed-off-by: Petr Vorel <pvorel@suse.cz>
---
 doc/style-guide.txt | 442 --------------------------------------------
 1 file changed, 442 deletions(-)
 delete mode 100644 doc/style-guide.txt

diff --git a/doc/style-guide.txt b/doc/style-guide.txt
deleted file mode 100644
index b853fa8dc..000000000
--- a/doc/style-guide.txt
+++ /dev/null
@@ -1,442 +0,0 @@
-LTP Style Guide
-===============
-
-**********************************************************************
-Welcome to the *LTP Project Coding Guideline* document! This document is
-designed to guide committers and contributors in producing consistent, quality
-deterministic testcases and port testcases from other sources to LTP so that
-they can be easily maintained by project members and external contributors.
-
-Please refer to the *Linux Kernel Coding Guidelines* unless stated otherwise
-in this document.
-
-Changelog:
-
- * Initial version: Ngie Cooper <yaneurabeya@gmail.com>
- * Reformatted for asciidoc: Cyril Hrubis <chrubis@suse.cz>
-**********************************************************************
-
-Using libltp
-------------
-
-Of course the manpages should be the primary source of information in
-terms of how you should use libltp, but this section provides a quick
-set of guidelines to hit the ground running with libltp.
-
-When you can use libltp please observe the following guidelines:
-
-1. Should I use tst_*() interface in forked processes?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-No, only use libltp in non-forked processes and functions +perror(3)+ /
-+exit(3)+ otherwise. Reason being:
-
- * Calling +tst_resm()+ from multiple processes is messy.
- * Calling cleanup can break test execution.
- * Establishing a complicated scheme of tracking the testcase state
-   for teardown is undesirable.
-
-2. Use SAFE_* macros
-~~~~~~~~~~~~~~~~~~~~
-
-Use +SAFE_*+ macros (see +safe_macros.h+) instead of bare calls to libcalls and
-syscalls. This will:
-
- * Reduce number of lines wasted on repeated in multiple files with
-   error catching logic.
- * Ensure that error catching is consistent and informative; all
-   +SAFE_*+ macros contain the line number of the failure as well as
-   the file where the failure occurred by design. So unless the
-   stack gets stomped on, you will be able to determine where
-   the failures occurred if and when they do occur with absolute
-   determinism.
- * Mute some unchecked return code warnings.
-
-3. Don't call cleanup() from within setup()
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Unless you need to clean up or reset system state that wouldn't otherwise be
-handled by a proper release of all OS resources.
-
-This includes (but is not limited to):
-
- * Memory mapped pages.
- * Mounted filesystems.
- * File descriptors (if they're in temporary directories, etc).
- * Temporary files / directories.
- * Waiting for child processes.
- * +/proc+ & +/sysfs+ tunable states.
-
-You don't need to clean up the following:
-
- * +malloc(3)+'ed memory.
- * Read-only file descriptors in persistent paths (i.e. not
-   temporary directories).
-
-Please be aware of some of the caveats surrounding forking,
-exec'ing and descriptor inheritance, etc.
-
-4. Call APIs that don't require freeing up resources on failure first
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
- * +tst_require_root()+
- * +tst_sig(...)+
- * +malloc(3)+
- * +tst_tmpdir()+
-
-That way you can simplify your setup and avoid calling cleanup whenever
-possible!
-
-5. If the test needs to run as root
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If the test need to run as root, check to make sure that you're root
-*before doing any other setup* via +tst_require_root()+.
-
-6. No custom reporting APIs
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Don't roll your own reporting APIs unless you're porting testcases or are
-concerned about portability.
-
-7. Handle TBROK and TFAIL correctly
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Use +TBROK+ when an unexpected failure unrelated to the goal of the testcase
-occurred, and use +TFAIL+ when an unexpected failure related to the goal of
-the testcase occurred.
-
-8. Don't roll your own syscall numbers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Header +lapi/syscalls.h+ exists for this purpose and does a pretty
-dang good job.
-
-9. Keep errors as short and sweet as possible
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-For example:
-[source,c]
-----------------------------------------------------
-if (fork() == -1)
-	tst_brkm(TBROK, cleanup, "fork failed");
-
-/* or */
-
-if (fork() == -1)
-	tst_brkm(TBROK, cleanup, "fork # 1 failed");
-
-if (fork() == -1)
-	tst_brkm(TBROK, cleanup, "fork # 2 failed");
-----------------------------------------------------
-
-If you can't determine where the failure has occurred in a testcase based on
-the entire content of the failure messages, then determining the cause of
-failure may be impossible.
-
-10. Reporting errno and the TEST() macro
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Don't roll your own +errno+ / +strerror()+ printout when you use +tst_resm()+
-calls. Use either +TERRNO+ or +TTERRNO+. Similarly, if a testcase passed and
-it's obvious why it passed (for example a function call returns +0+ or
-+TEST_RETURN == 0+).
-
-[source,c]
--------------------------------------------------------------------------------
-/* Example without TEST(...) macro */
-
-exp_errno = ENOENT;
-
-if (fn() == -1) {
-	/*
-	 * Using TERRNO here is valid because the error case
-	 * isn't static.
-	 */
-	if (exp_errno == ENOENT)
-		tst_resm(TPASS|TERRNO,
-		    "fn failed as expected");
-	/*
-	 * Using strerror(TEST_ERRNO) here is valid because
-	 * the error case isn't static.
-	 */
-	else
-		tst_resm(TFAIL|TERRNO,
-		    "fn failed unexpectedly; expected "
-		    "%d - %s",
-		    exp_errno, strerror(exp_errno));
-} else
-	tst_resm(TBROK, "fn passed unexpectedly");
-
-/* Example using TEST(...) macro */
-
-TEST(fn());
-if (TEST_RETURN == 0)
-	tst_resm(TPASS, "fn passed as expected");
-else
-	tst_resm(TFAIL|TTERRNO, "fn failed");
--------------------------------------------------------------------------------
-
-[NOTE]
-The +TEST()+ macro is not thread-safe as it saves return value and errno into
-global variable.
-
-12. Use tst_brkm() when possible
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Use...
-[source,c]
-------------------------------
-tst_brkm(TBROK, cleanup, ...);
-------------------------------
-...instead of...
-[source,c]
-------------------------------
-tst_resm(TBROK, ...);
-cleanup();
-tst_exit();
-------------------------------
-
-[NOTE]
-As you see the +tst_brkm()+ no longer requires non +NULL+ cleanup_fn argument
-in order to call +tst_exit()+.
-
-13. Indentation
-~~~~~~~~~~~~~~~
-
-Use hard tabs for first-level indentation, and 4 spaces for every line longer
-than 80 columns. Use a linebreak with string constants in format functions
-like +*printf()+, the +tst_resm()+ APIs, etc.
-
-Example:
-[source,c]
--------------------------------------------------------------------------------
-if ((this_is_a_poorly_formed_really_long_variable = function_call()) == NULL &&
-    statement1() && i < j && l != 5) {
-	/* Use tabs here */
-	printf("The rain in Spain falls mainly in the plain.\nThe quick brown "
-	    "fox jumped over the lazy yellow dog\n");
-	tst_resm(TPASS,
-	    "Half would turn and fight. The other half would try to swim "
-	    "across. But my uncle told me about a few that... they'd swim "
-	    "halfway out, turn with the current, and ride it all the way out "
-	    "to sea. Fisherman would find them a mile offshore, swimming.");
-}
--------------------------------------------------------------------------------
-
-14. System headers
-~~~~~~~~~~~~~~~~~~
-
-Don't use +linux/+ headers if@all possible. Usually they are replaced with
-+sys/+ headers as things work their way into glibc.  Furthermore, +linux/+
-headers get shuffled around a lot more than their +sys/+ counterparts it
-seems.
-
-15. Signal handlers
-~~~~~~~~~~~~~~~~~~~~
-
-Avoid doing tricky things in signal handlers. Calling most of the libc
-functions from signal handler may lead to deadlocks or memory corruption.  If
-you really need to do anything more complicated that +should_run = 0;+ in your
-signal handler consult +man 7 signal+ for async-signal-safe functions.
-
-Porting Testcases
------------------
-
-If one of the following is true...
-
- 1. You are porting a testcase directly to LTP which doesn't need to
-    be ported outside of Linux.
- 2. The beforementioned project or source is no longer contributing
-    changes to the testcases.
-
-Then please fully port the testcase(s) to LTP. Otherwise, add robust porting
-shims around the testcases using libltp APIs to reduce longterm maintenance
-and leave the sources alone so it's easier to sync the testcases from the
-upstream source.
-
-New Testcases
--------------
-
- 1. Always use libltp for Linux centric tests. No ifs, ands, or buts
-    about it.
- 2. Sort headers, like:
-
-[source,c]
----------------------------------------------------------------------------
-/*
- * sys/types.h is usually (but not always) required by POSIX
- * APIs.
- */
-#include <sys/types.h>
-/* sys headers, alphabetical order. */
-/* directory prefixed libc headers. */
-/* non-directory prefixed libc headers. */
-/* directory prefixed non-libc (third-party) headers. */
-/* non-directory prefixed non-libc (third-party) headers. */
-/* Sourcebase relative includes. */
-
-/* e.g. */
-
-#include <sys/types.h>
-#include <sys/stat.h>
-#include <netinet/icmp.h>
-#include <stdio.h>
-#include <dbus-1.0/dbus/dbus.h>
-#include <archive.h>
-#include "foo/bar.h"
-#include "test.h"
----------------------------------------------------------------------------
-
-3. Comments
-~~~~~~~~~~~
-
-Do not use obvious comments ("child process", "parse options", etc). This
-leads to visual comment noise pollution.
-
-4. Inline assignments
-~~~~~~~~~~~~~~~~~~~~
-
-Don't do inline assignment, i.e.
-
-[source,c]
----------------------------------------------------------------------------
-int foo = 0;
-
-Use separate statements:
-
-int foo;
-
-foo = 0;
----------------------------------------------------------------------------
-
-The only exception to this is when you define global variables.
-
-5. How to assert test is running as root?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Your testcase should be runnable as root and non-root. What does that mean? It
-should fail gracefully as non-root if it has insufficient privileges, or use
-+tst_require_root()+ if root access is absolutely required.
-
-A lot of newer testcases don't honor this fact and it causes random
-unnecessary errors when run as non-privileged users.
-
-6. Do I need to create temporary directory?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Use +tst_tmpdir()+ if your testcase will:
-
-* Create temporary files.
-* Dump core.
-* Etc. Otherwise, don't bother with the API.
-
-[NOTE]
-If you created temporary directory with +tst_tmpdir()+ don't forget to call
-+tst_rmdir()+ when the test is cleaning up. This is *NOT* done automatically.
-
-7. Setting up signal handlers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Use +tst_sig()+ instead of bothering with sigaction / signal. This reduces
-potential of leaving a mess around if your test doesn't exit cleanly (now,
-there are some signals that can't be blocked, i.e. +SIGKILL+ and +SIGSTOP+,
-but the rest can be caught).
-
-8. Basic template
-~~~~~~~~~~~~~~~~~
-
-The following is a basic testcase template:
-[source,c]
----------------------------------------------------------------------------
-#include "test.h"
-
-char *TCID = "testname";
-int TST_TOTAL = /* ... */
-
-static void setup(void)
-{
-	/* ... */
-
-	tst_require_root();
-
-	tst_tmpdir();
-
-	/* ... */
-
-	TEST_PAUSE;
-}
-
-static void cleanup(void)
-{
-
-	TEST_CLEANUP;
-
-	/* ... */
-
-	tst_rmdir();
-}
-
-int main(void)
-{
-	/* ... */
-
-	setup();	/* Optional */
-
-	cleanup();	/* Optional */
-	tst_exit();	/* DON'T FORGET THIS -- this must be last! */
-}
----------------------------------------------------------------------------
-
-Fixing Legacy Testcases
------------------------
-
-Unless you interested in exercising self-masochism, do minimal changes
-to testcases when fixing them so it's easier to track potential
-breakage in testcases after a commit is made (mistakes happen and no
-one is perfect). If it works after you fix it -- great -- move on.
-It's more the job of the committers / maintainers to do things like
-style commits.
-
-It's better to focus on adding more content to LTP as a contributor
-and fixing functional issues with existing tests than it is worrying
-about whitespace, unnecessary pedanticness of function calls, etc.
-
-As ugly as the style is in the surrounding code may be, stick to it.
-Otherwise anyone reading the code will cringe at the chaos and
-non-uniform `style', and it will be more difficult to fix later.
-
-
-Fixing Open Posix Testsuite
----------------------------
-
-The *Open Posix Testsuite* does not use libltp interface and moreover aims to
-be usable on any *POSIX* compatible operating system.
-
-So *NO* Linux, BSD specific syscalls there.
-
-Contribution to the project
----------------------------
-
-Since CVS is effectively dead for LTP proper, we ask that you submit
-patches that are git friendly and patchable.
-
-Guidelines for submitting patches are as follows:
-
-1. Use +git commit -s+ . You know you want to ;) .. (you may need to
-   submit a correct signed-off-by line, e.g. use git config first).
-2. Provide a short (<= 50 character) description of the commit.
-3. Provide a little more terse (1-2 paragraph maximum, <= 72 character
-   lines) description of what the commit does.
-4. Format the email with +git format-patch --attach+ command .
-
-Example of a commit message:
-
--------------------------------------------------------------------
-Short description of my commit.
-
-This is a much longer description of my commit. Blah blah blah blah
-blah blah blah blah blah.
-
-Signed-off-by: John Smith <dev@null>
--------------------------------------------------------------------
-- 
2.25.1

[LTP] [PATCH 2/2] doc: Add note about LAPI headers

[Petr Vorel]

into the Test Writing Guidelines.

Signed-off-by: Petr Vorel <pvorel@suse.cz>
---
Hi,

Maybe some of this text belongs to library-api-writing-guidelines.txt,
not sure.

Kind regards,
Petr

 doc/test-writing-guidelines.txt | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/doc/test-writing-guidelines.txt b/doc/test-writing-guidelines.txt
index 9ff70b1bc..45bac223f 100644
--- a/doc/test-writing-guidelines.txt
+++ b/doc/test-writing-guidelines.txt
@@ -327,6 +327,15 @@ time may vary arbitrarily, for these timeout can be disabled by setting it to
 Test can find out how much time (in seconds) is remaining to timeout,
 by calling 'tst_timeout_remaining()'.
 
+LAPI headers
+++++++++++++
+
+Use our LAPI headers ('include "lapi/foo.h"') to keep compatibility with old distributions.
+LAPI header should always include original header. Older linux headers were problematic,
+therefore we preferred to use libc headers. There are still some bugs when
+combining certain glibc headers with linux headers, see
+https://sourceware.org/glibc/wiki/Synchronizing_Headers.
+
 A word about the cleanup() callback
 +++++++++++++++++++++++++++++++++++
 
-- 
2.25.1