diff options
Diffstat (limited to 'longbow/documentation/LaTeX Documentation')
| -rw-r--r-- | longbow/documentation/LaTeX Documentation/.gitignore | 7 | ||||
| -rw-r--r-- | longbow/documentation/LaTeX Documentation/Abstract.tex | 7 | ||||
| -rw-r--r-- | longbow/documentation/LaTeX Documentation/Document.tex | 730 | ||||
| -rw-r--r-- | longbow/documentation/LaTeX Documentation/LongBow.tex | 37 | ||||
| -rw-r--r-- | longbow/documentation/LaTeX Documentation/PARCOneColumn.cls | 288 | ||||
| -rw-r--r-- | longbow/documentation/LaTeX Documentation/Packages.tex | 58 | ||||
| -rw-r--r-- | longbow/documentation/LaTeX Documentation/Title.tex | 13 | ||||
| -rw-r--r-- | longbow/documentation/LaTeX Documentation/old/Longbow_documentation.tex | 769 | ||||
| -rwxr-xr-x | longbow/documentation/LaTeX Documentation/old/SelfArx2.cls | 191 | ||||
| -rw-r--r-- | longbow/documentation/LaTeX Documentation/parc_black_solid.png | bin | 0 -> 24543 bytes |
10 files changed, 2100 insertions, 0 deletions
diff --git a/longbow/documentation/LaTeX Documentation/.gitignore b/longbow/documentation/LaTeX Documentation/.gitignore new file mode 100644 index 00000000..a9f1afaf --- /dev/null +++ b/longbow/documentation/LaTeX Documentation/.gitignore @@ -0,0 +1,7 @@ +.texpadtmp +*.aux +*.log +*.pdf +*.out +*.toc +*.synctex.gz diff --git a/longbow/documentation/LaTeX Documentation/Abstract.tex b/longbow/documentation/LaTeX Documentation/Abstract.tex new file mode 100644 index 00000000..0c394e76 --- /dev/null +++ b/longbow/documentation/LaTeX Documentation/Abstract.tex @@ -0,0 +1,7 @@ +%- +% ABSTRACT +%- +% +\Abstract{Software testing, validation, and measurable quality metics are an important element in modern software development. +LongBow is a software framework and facility for writing software using invariants, runtime validation, unit testing, and code analysis for the C programming language. +} diff --git a/longbow/documentation/LaTeX Documentation/Document.tex b/longbow/documentation/LaTeX Documentation/Document.tex new file mode 100644 index 00000000..273336ef --- /dev/null +++ b/longbow/documentation/LaTeX Documentation/Document.tex @@ -0,0 +1,730 @@ +\begin{document} + +\flushbottom % Makes all text pages the same height + +\maketitle % Print the title and abstract box + +% Use the multicols package to a make multi-column table of contents. +\begin{multicols}{2} +\tableofcontents +\end{multicols} + +%For a single column table of contents just use this +%\tableofcontents % Print the contents section + +\thispagestyle{empty} % Removes page numbering from the first page + +%\newcommand{\HRule}{\rule{\linewidth}{0.5mm}} % Defines a new command for the horizontal lines, change thickness here + +\section{Overview} % The \section{} command stops section numbering + +LongBow is software to help you write better C programs. It provides: +\begin{itemize} +\item A run-time assertion facility to establish strict rules on the state of your program. +\item A testing facility based on the xUnit testing model. +\item Compile-time assistance for writing code meant to be compiled by compilers with different features. +\end{itemize} + +LongBow can help you find and manage problems early, establish and maintain confidence in the correctness of your code, make collaboration easier, facilitate future change, and improve overall design. + +LongBow allows you to take control and establish invariant pre- and post-conditions that detect inconsistencies and unexpected results in your programs in order to find bugs and design deficiencies in the code during development rather than waiting for others to find your bugs for you. + +\section{Set up and installation} +How to install, configure, link, and run LongBow. + +\subsection {Installation} +Get the tar file from xxx. +untar and do a make install. +The resulting LongBow directory will contain the C header files, C source files, and runtime libraries needed. + +\subsection {Configuration} + +\subsubsection{LongBow with LLDB} +The {\tt lldb} debugger is aware when C source files (not header files) are included in another source file. +This induces a problem where the breakpoints in the included source files are not set. +But you can configure lldb to set them: In the file {\tt \~/.lldbinit}, +add the line: + +\begin{lstlisting} +settings set target.inline-breakpoint-strategy always +process handle -p true -s false SIGABRT +\end{lstlisting} + +\subsubsection{LongBow with GDB} +LongBow uses signals to interrupt program flow when an assertion fails. +When using gdb this will cause gdb to stop running of the test. +This probably isn't what you want and would rather prefer that gdb just +ignore the signal and let the LongBow unit test signal handler take care of the signal. +To do this, you must configure gdb to ignore the signal and to allow it to pass to the program being executed. +In the file {\tt \~/.gdbinit}, add the line: + +\begin{lstlisting} +handle 6 nostop pass +\end{lstlisting} + +\subsubsection{Linking and Libraries} +There are two LongBow libraries that must be linked with the application: the primary LongBow library, (\url{liblongbow.a}) and one of the LongBow reporter libraries. +The reporter libraries enable the reporting mechanism for Longbow. +Currently two reporter libraries have been implemented: +\begin{enumerate} +\item \url{liblongbow-plaintext.a} which displays output as simple text; and +\item \url{liblongbow-ansiterm.a} which displays output as an ANSI colorized output. +\end{enumerate} + +Both display to standard output. + +\subsubsection{Running and Runtime Behavior} +You can "run" Longbow in one of two ways: you can run your application with assertions turned on in order to test expected invariance during runtime; or you can run your tests using Longbow's Test Runner. +Turning off assertions for runtime is not currently supported. + +\section{Programming with Assertions} + +Longbow's Assertions offer a way to check runtime invariance throughout your program. +Traps are a subset of Assertions that are executed at runtime even if Assertions have been turned off during deployment. They should be used when program failure is the correct response to assertion failure. + +The assertion framework is based on the following design principles: +\begin{itemize} +\item It is intentionally simple and can be extended. +\item You don't have to change your program design to accommodate assertions. +\item It is designed specifically for C programs. +\item It is based on programming with invariance. +\item Assertions may be used only during development as a debugging aid, or in deployment as well to offer more descriptive errors to users. +\end{itemize} + + +\subsection{Designing with Assertions } +Assertions can be used to debug code and give better information about errors to users. +They should not be used for error handling. +Assertions should be used to explicitly test for conditions that must be true in order for an operation to work. Examples include testing for NULL pointers, out-of-bounds array indices, and incorrect dependent relationships. Ultimately your code should work every time under all input conditions without ever triggering an assertion although passing tests don't guarantee proper design. You should aim for 100\% code coverage. + +Be strategic about where the assertions are located and what they test for. +A failed assertion should be considered a bug should be treated as such. +For example a failure to open a file is likely not a bug in your program, per se, but indicative of some other problem and programmatic error handling would probably be the best approach to handling the missing file. + +Assertions can be included or excluded at compile-time. In many cases, it is reasonable to keep the assertions in production releases as an aid to future bug reporting. + +\subsection{Using the Assertion Libraries } + +LongBow provides a basic set of assertions that test a condition and trigger the assertion if the condition fails to be true. When an assertion triggers the following occurs: +\begin{itemize} +\item An Event is created which records the kind of assertion that failed and the location of the assertion's failure. +\item The formatted message of the failed assertion is reported via the LongBow report library. +\item The running program is sent a {\tt SIGABRT} signal. +\end{itemize} + +The following four assertions are currently supported: +\begin{itemize} +\item {\tt assertTrue} +\item {\tt assertFalse} +\item {\tt assertNull} +\item {\ttfamily assertNotNull} +\end{itemize} + +The function signatures for assertions follow the pattern: + +\Cfunctiondef{\tt void}{assertX}{{\it condition}, {\tt "message", ...}} + +Where {\tt "message"} is a printf(3) format, nul-terminated C-String that will be displayed when the assertion triggers. The ... represents the arguments that might be used to create the string. + +There is one C header file that must be required to use the assertion mechanism: +\begin{itemize} +\item \textbf{LongBow/runtime.h} is the basic header file needed for assertions. +\end{itemize} + +\subsection {Using Traps} +LongBow traps are subsets of assertions and are intended for simple error reporting. +There is no functional difference between a trap and an assertion, however, a traps cannot be shut off during runtime so they are good to use for deployment if you plan to turn assertions off and the program should terminate when the assertion is not met. + +Traps take as arguments a condition and a printf(3) format C string of explanatory text along with any values necessary to format the string. + +A typical trap function signature is: + +\Cfunctiondef{\tt void}{trap{\it Kind}}{{\it condition}, {\tt "message", ...}} + +Where {\it Kind} represents the kind of trap (see {\tt LongBow/traps.h}. +If the {\it condition} is evaluated to {\tt true}, the trap is triggered. + +where {\tt ...} is the printf format string and values. + +\noindent Currently supported traps are defined in \texttt{traps.h} and include: +\begin{itemize} +\item \textbf{trapIllegalValue:} Used for capturing failed parameter validation, for example. +\item \textbf{trapIllegalValueIf:} Used to trap an illegal value if a condition is met. +\item \textbf{trapNotImplemented:} Used to report and abort an unimplemented capability. +\item \textbf{trapOutOfBounds:} Used to trap an out-of-bounds condition on an index. +\item \textbf{trapOutOfBoundsIf:} Used to trap an out-of-bounds condition for a specific value. +\item \textbf{trapOutOfMemory:} Used to signal that no more memory can be allocated. +\item \textbf{trapUnexpectedState:} Used to signal that an unexpected or inconsistent state was encountered. +\item \textbf{trapUnexpectedStateIf:} If the given condition is true, used to signal that an unexpected state was encountered. +\item \textbf{trapUnrecoverableState:} Used to report an unrecoverable state in program execution. +\end{itemize} + +\subsection{Examples } + +\paragraph {assertNotNull example} + +\begin{lstlisting} +#include <LongBow/assertions> +#include <unistd.h> +#include <string.h> + +void +function(char *pointer) +{ + assertNotNull(pointer, "The pointer cannot be NULL."); + + write(1, pointer, strlen(pointer)); +} + +int +main(int argc, char *argv[]) +{ + function(0); +} +\end{lstlisting} + + +In this case the {\tt assertNotNull} will trigger and the program will immediately terminate with the following output: + +\begin{lstlisting} +Assert pointer.c:8 function() pointer != NULL The pointer cannot be NULL. +0 pointer 0x0000000107840d4c function + 188 +1 pointer 0x0000000107840dd1 main + 33 +2 libdyld.dylib 0x00007fff887595fd start + 1 + +\end{lstlisting} + +\paragraph {assertTrue example} + +\begin{lstlisting} +LONGBOW_TEST_CASE(Global, myTest) +{ + struct timeval timeval; + timeval.tv_sec = 0; + timeval.tv_usec = 1000; + + char *expected = "0.001000"; + char *actual = parcTime\_FormatTimeval(timeval); + assertTrue(strcmp(expected, actual) == 0, "Expected \%s, actual \%s", expected, actual); + parc_free(actual); +} + \end{lstlisting} + +\paragraph{Example using assertNull, assertNotNull, and assertTrue} + +\begin{lstlisting} +static void +parcDeque_AssertInvariants(const PARCDeque *deque) +{ + assertNotNull(deque, "Parameter cannot be null."); + if (deque->head != NULL) { + assertTrue(deque->size != 0, "PARCDeque head is not-null, but size is zero."); + assertNotNull(deque->tail, "PARCDeque head is not-null, but tail is null."); + parcDequeNode_AssertInvariants(deque->head); + parcDequeNode_AssertInvariants(deque->tail); + } else { + assertNull(deque->tail, "PARCDeque head is null, but tail is not null."); + assertTrue(deque->size == 0, "PARCDeque head is null, but size is not zero."); + } +} + +\end{lstlisting} + +\paragraph {assertFalse example} +\begin{lstlisting} +RtaCommand * +rtaCommand_Read(int fd) +{ + ssize_t readlen; + uint32_t netbyteorder; + size_t len; + char *p; + RtaCommand *command; + + readlen = read(fd, &netbyteorder, 4); + assertFalse(readlen < 0, "socket read error: \%s\n", strerror(errno)); + assertTrue(readlen == 4, "Partial read on command length"); + + len = ntohl(netbyteorder); + p = parc_malloc(len); + readlen = read(fd, p, len); + assertTrue(readlen == len, "Partial read on command"); + + command = rtaCommand_Parse(p); + parc_free(p); + return command; +} +\end{lstlisting} + + +\section{Unit testing} +Longbow provides an xUnit-style unit testing framework. The framework is a mechanism for organizing and running trees of test code. It is organized hierarchically into three components: a Test Runner, Test Fixtures, and Test Cases. + +A Test Runner file is associated 1:1 with a C source file, with the word "test\_" prepended on the C source file name. For example, the Test Runner file for {\tt parc\_Buffer.c} would be {\tt test\_parc\_Buffer.c}. +This file contains all of the Test Fixtures and Test Cases needed to test the associated C source file. + +Each Test Runner will run a set of Test Fixtures. +Test Fixtures are an organizational unit that allows you to group your Test Cases. +The grouping may be done by functionality, by static vs non static functions, or by any other organizing principle that you choose. + +A Test Fixture runs a set of Test Cases each of which is responsible for testing some aspect of the C module. + +Tests are run in the order they are defined. +The Test Runner will start with Test Fixture1 and all of its Test Cases, move on to Test Fixture2 and its Test Cases etc. Tests should be idempotent, however, and not assume any particular order or be dependent on each other. +They should not leave state such that the next Test Case inherits that state. + +%\subsection{Designing tests } +%\textcolor{red}{Put something here} + +\subsection{Writing tests with the Test Runner module } +\subsubsection{Test Runners} +A Test Runner is the top-level executable unit in a test. +It is responsible for establishing the necessary state for the set of tests it contains, executing the tests via Test Fixtures and Test Cases, and tearing down state when the tests have completed. + +A Test Runner requires the following header files: +\begin{itemize} +\item \textbf{LongBow/runtime.h} is the basic header file needed for assertions and testing. +\item \textbf{LongBow/unit-test.h} is the basic header file needed for testing. +\item \textbf{LongBow/compiling.h} is used when you have code that needs to work across multiple compilers - it contains the matrix of compiler and / you are using. +\end{itemize} + +\noindent The source code of a Test Runner has the following basic structure: + +\begin{lstlisting} +#include <LongBow/testing.h> + +LONGBOW_TEST_RUNNER(myRunner) +{ +} + +LONGBOW_TEST_RUNNER_SETUP(myRunner) +{ + // Code to set up required state + return LONGBOW_STATUS_SUCCEEDED; +} + +LONGBOW_TEST_RUNNER_TEARDOWN(myRunner) +{ + //Code to clean up state + return LONGBOW_STATUS_SUCCEEDED; +} + +\end{lstlisting} + + +Each of these functions has a local variable - {\tt LongBowRunner *testRunner} - which may be used to manipulate the clipboard (as an example). The Text Fixtures and Test Cases launched by the Test Runner will have access to this variable as well as their own local variable. Thus a Test Fixture will have access to the {\tt testRunner} that is passed to it as well as its own {\tt LongBowFixture *testFixture} and a Test Case will have access to {\tt testRunner, testFixture} and its own {\tt LongBowCase *testCase}. + +\subsubsection{Test Fixtures} + +A Test Fixture is a subcomponent which has the same structure as a Test Runner. +The following code adds Test Fixture to a Test Runner: + +\begin{lstlisting} +LONGBOW_TEST_RUNNER(myRunner) +{ + LONGBOW_RUN_TEST_FIXTURE(Global); + LONGBOW_RUN_TEST_FIXTURE(Local); +} +\end{lstlisting} + + +Like the Test Runner, it is responsible for setting up and tearing down state needed by the Test Cases. + +\begin{lstlisting} + +LONGBOW_TEST_FIXTURE(Global) +{ + LONGBOW_RUN_TEST_CASE(Global, myTest); +} + +LONGBOW_TEST_FIXTURE_SETUP(Global) +{ + return LONGBOW_STATUS_SUCCEEDED; +} + +LONGBOW_TEST_FIXTURE_TEARDOWN(Global) +{ + return LONGBOW_STATUS_SUCCEEDED; +} +\end{lstlisting} + +\subsubsection{Test Cases} +Test Cases are the leaf nodes of the testing tree. Each Test Case tests one aspect of the C module. + +\paragraph {Handling Test Case state safely} + +Every Test Case has access to a private \"clipboard\" that contains data shared between the Test Case and the set up and teardown functions of its encapsulating Test Fixture. +This shared state is used to provide specific environment or initialized variables for the test and for the test to communicate specialized information to the teardown function. + +For example, a Test Case which is expected to fail as the result of testing a failure condition might exit without releasing resources which are left in an unsafe state. +As multiple tests may be run in one process, it is important to clean these up before launching the next test. + +The following example demonstrates the clipboard mechanism: +\begin{itemize} +\item{The Test Fixture setup function allocates the necessary resources and puts references to them into the clipboard.} +\item{The Test Case gets these references, uses them, and fails.} +\item{The Test Fixture tear-down function obtains the resources from the clipboard and deallocates them.} +\end{itemize} + +\subsubsection {Test Runner Example} +The following is an example of a test file : + +\begin{lstlisting} +#include <stdio.h> +#include <string.h> + +#include <LongBow/testing.h> +#include <LongBow/debugging.h> + +LONGBOW_TEST_RUNNER(testClipboard) +{ + LONGBOW_RUN_TEST_FIXTURE(Global); +} + +LONGBOW_TEST_RUNNER_SETUP(testClipboard) +{ + return LONGBOW_STATUS_SUCCEEDED; +} + +LONGBOW_TEST_RUNNER_TEARDOWN(testClipboard) +{ + return LONGBOW_STATUS_SUCCEEDED; +} + +LONGBOW_TEST_FIXTURE(Global) +{ + LONGBOW_RUN_TEST_CASE(Global, testClipboard); +} + +LONGBOW_TEST_FIXTURE_SETUP(Global) +{ + char *testData = strdup("Hello World"); + longBowTest Case_SetClipBoardData(testCase, testData, free); + + return LONGBOW_STATUS_SUCCEEDED; +} + +LONGBOW_TEST_FIXTURE_TEARDOWN(Global) +{ + return LONGBOW_STATUS_SUCCEEDED; +} + +LONGBOW_TEST_CASE(Global, testClipboard) +{ + char *testData = longBowTest Case_GetClipBoardData(testCase); + printf("Shared state '%s'\n", testData); +} + +int +main(int argc, char *argv[]) +{ + LongBowRunner *testRunner = LONGBOW_TEST_RUNNER_CREATE(testClipboard); + int exitStatus = LONGBOW_TEST_MAIN(argc, argv, testRunner); + longBowTest Runner_Destroy(&testRunner); + exit(exitStatus); +} +\end{lstlisting} + +\subsubsection {Testing for Successful Failure} +Testing for success is straightforward but we also may have to test that something fails when it is supposed to. +This section describes how to test for an expected non-success result. + +To compose a Test Case that expects a result other than success, use the {\tt LONGBOW\_TEST\_CASE\_EXPECTS} function which takes the expected event as a parameter and completes. The example below shows the capture of a successful segmentation fault. + + +\begin{lstlisting} +#include <stdio.h> +#include <sys/types.h> +#include <signal.h> + +#include <LongBow/unit-test.h> + +LONGBOW_TEST_RUNNER(LongBow) +{ + LONGBOW_RUN_TEST_FIXTURE(MyFixture); +} + +LONGBOW_TEST_RUNNER_SETUP(LongBow) +{ + return LONGBOW_STATUS_SUCCEEDED; +} + +LONGBOW_TEST_RUNNER_TEARDOWN(LongBow) +{ + return LONGBOW_STATUS_SUCCEEDED; +} + +LONGBOW_TEST_FIXTURE(MyFixture) +{ + LONGBOW_RUN_TEST_CASE(MyFixture, alwaysSEGV); +} + +LONGBOW_TEST_FIXTURE_SETUP(MyFixture) +{ + return LONGBOW_STATUS_SUCCEEDED; +} + +LONGBOW_TEST_FIXTURE_TEARDOWN(MyFixture) +{ + return LONGBOW_STATUS_SUCCEEDED; +} + +LONGBOW_TEST_CASE_EXPECTS(MyFixture, alwaysSEGV, .event = &LongBowEventSIGSEGV) +{ + int *p = 0; + int i = *p; +} + +int +main(int argc, char *argv[]) +{ + LongBowRunner *testRunner = LONGBOW_TEST_RUNNER_CREATE(LongBow); + int status = LONGBOW_TEST_MAIN(argc, argv, testRunner, NULL); + longBowTest Runner_Destroy(&testRunner); + + exit(status); +} + +\end{lstlisting} + +\subsection{Running tests} + +The overall process for writing and running your tests: +\begin{itemize} +\item Write a Test Runner file for every .c file that completely tests all of the code container in the .c file. This filename should be "test\_" prepended to the name of the file you are testing. +\item Compile the Test Runner file with one of: +\begin {itemize} +\item -llongbow -llongbow-ansiterm +\item -llongbow -llongbow-textplain +\end{itemize} +\item Execute the Test Runner. +\end{itemize} + + +\subsection{Examples } + +Here is an example of a C source file and its associated Test file. Tutorial.c is a small C program which simply provides an uninteresting but useful exemplar of the test framework. + + +\noindent \textbf{Tutorial.c} + +\begin{lstlisting} +#include <unistd.h> +#include <stdbool.h> +#include <signal.h> + +static bool +_privateFunction() +{ + return true; +} + +bool +alwaysSucceed() +{ + return _privateFunction(); +} + +bool +alwaysFail() +{ + return false; +} + +bool +blowUp() +{ + char *p = 0; + *p = 0; + + return true; +} + +\end{lstlisting} + +The following code is the test file for the Tutorial.c. Note that the file name is simply the C source file name with "test\_" prepended. In this example, the Test Runner divides the Test Cases into two Test Fixtures: one to focus on the Static functions and one to focus on the Global functions. + +\noindent \textbf{test\_Tutorial.c} +\begin{lstlisting} + +#include "tutorial.c" + +#include <LongBow/unit-test.h> + + +LONGBOW_TEST_RUNNER(myTutorialTest) +{ + LONGBOW_RUN_TEST_FIXTURE(Static); + LONGBOW_RUN_TEST_FIXTURE(Global); +} + +LONGBOW_TEST_RUNNER_SETUP(myTutorialTest) +{ + return LONGBOW_STATUS_SUCCEEDED; +} + +LONGBOW_TEST_RUNNER_TEARDOWN(myTutorialTest) +{ + return LONGBOW_STATUS_SUCCEEDED; +} + +LONGBOW_TEST_FIXTURE(Global) +{ + LONGBOW_RUN_TEST_CASE(Global, alwaysSucceed); + LONGBOW_RUN_TEST_CASE(Global, alwaysFail); + LONGBOW_RUN_TEST_CASE(Global, blowUp); + +} + +LONGBOW_TEST_FIXTURE_SETUP(Global) +{ + return LONGBOW_STATUS_SUCCEEDED; +} + +LONGBOW_TEST_FIXTURE_TEARDOWN(Global) +{ + return LONGBOW_STATUS_SUCCEEDED; +} + +LONGBOW_TEST_CASE(Global, alwaysSucceed) +{ + bool result = alwaysSucceed(); + + assertTrue(result, "This test must always succeed."); +} + +LONGBOW_TEST_CASE(Global, alwaysFail) +{ + bool result = alwaysFail(); + + assertTrue(result, "This test will fail."); +} + +LONGBOW_TEST_CASE_EXPECTS(Global, blowUp, .event = &LongBowEventSIGSEGV) +{ + blowUp(); + + assertTrue(false, "This will not be executed"); +} + + +LONGBOW_TEST_FIXTURE(Static) +{ + LONGBOW_RUN_TEST_CASE(Static, _privateFunction); +} + +LONGBOW_TEST_FIXTURE_SETUP(Static) +{ + return LONGBOW_STATUS_SUCCEEDED; +} + +LONGBOW_TEST_FIXTURE_TEARDOWN(Static) +{ + return LONGBOW_STATUS_SUCCEEDED; +} + +LONGBOW_TEST_CASE(Static, _privateFunction) +{ + bool result = _privateFunction(); + + assertTrue(result, "This test must always succeed."); +} + +int +main(int argc, char *argv[argc]) +{ + LongBowRunner *testRunner = LONGBOW_TEST_RUNNER_CREATE(myTutorialTest); + int status = LONGBOW_TEST_MAIN(argc, argv, testRunner); + + longBowTest Runner_Destroy(&testRunner); + exit(status); +} + +\end{lstlisting} + +\section {Compiling and Compiler Support} +LongBow consolidates a variety of compile-time options that you include in your code. + +For example, the C99 standard defines the pragma operator and various compilers support this in various ways. + +\section{The LongBow Reporter} +The Longbow reporter offers a more user-friendly option for viewing the output of the running tests. In addition to linking with the primary LongBow library ({\tt liblongbow.a}), you also need to link with one of the following reporting libraries to control presentation of the test output. +\begin{itemize} +\item {\bf liblongbow-ansiterm.a} This option produces output that is color coded to indicate the degree of success: green for a successful test; yellow for warnings; and red for failure. +\item {\bf liblongbow-plaintext.a} This option produces plain text output. +\item {\bf liblongbow-json.a} This option is in development and will produce output in JSON format. +\end{itemize} + + + +\section {Appendices} +\subsection {Function Documentation} +The following modules are included in LongBow: +\begin {itemize} +\item \textbf{Runtime:} LongBow functions and macros for runtime. +\item \textbf{Testing:} LongBow functions and macros for writing tests. +\item \textbf{Internals:} LongBow functions and macros used internally. +\item \textbf{Reporting:} LongBow functions and definitions for writing report libraries. +\item \textbf{Performance testing:} LongBow functions and definitions for writing performance tests. +\end{itemize} + +\paragraph {Runtime} +LongBow runtime support consists primarily of assertions and traps. Developers insert assertions to insist that certain conditions are true before permitting the program to continue. If the assertion fails, the program is abnormally terminated. It uses the following files: + +\begin{itemize} +\item {\bf assertions.h:} Runtime and Test Assertions. + \item {\bf longBow\_EventType.h:} LongBow Events and Support. + \item {\bf longBow\_Runtime.h:} The LongBow Runtime support. + \item {\bf runtime.h:} LongBow Runtime Support. + \item {\bf traps.h:} Runtime and Test Traps. +\end{itemize} + + +\paragraph {Testing} +LongBow testing support consists of macros and ancillary functions to implement an xUnit style of writing and running tests. Test writers create a LONGBOW\_TEST\_RUNNER function which invokes one or more LONGBOW\_TEST\_FIXTURE functions, each of which invoke a specific LONGBOW\_TEST\_CASE. It uses the following files: + +\begin{itemize} +\item {\bf longBow\_EventType.h:} LongBow Events and Support. + \item {\bf longBow\_Main.h:} A main() function to run one or more LongBow Test Runners. + \item {\bf longBow\_OpenFile.h:} LongBow support for files and file descriptors. + \item {\bf longBow\_Runner.h:} LongBow Test Runner Support. + \item {\bf longBow\_Status.h} A simple status representation for a LongBow Test Case. + \item {\bf longBow\_Test CaseClipBoard.h:} LongBow Clipboard shared between the setup, test case, and teardown. + \item {\bf longBow\_UnitTesting.h} Unit Testing Support. . + \item {\bf testing.h:} LongBow testing functionality. + \item {\bf unit-test.h} LongBow Unit Test Support. +\end{itemize} + +\paragraph {Internals} +LongBow functions and macros used internally. +It uses the following files: + +\begin{itemize} + \item {\bf longBow\_ArrayList.h} A simple, list implementation using a dynamic array. + \item {\bf longBow\_Backtrace.h} Support for Stack Traces. + \item {\bf longBow\_Configuration.h} Support for LongBow Configuration. + \item {\bf longBow\_Debugging.h} Support for LongBow and Application Debugging. + \item {\bf longBow\_Event.h} LongBow Event Support. + \item {\bf longBow\_EventType.h} LongBow Events and Support. + \item {\bf longBow\_Fixture.h} Manage the execution of Test Cases. + \item {\bf longBow\_Location.h} LongBow Source File Location. + \item {\bf longBow\_Test Case.h} The interface and supporting functionality of a LongBow Test Case. + \item {\bf longBow\_Test CaseResult.h} LongBow Test Case Results. +\end{itemize} + + + \paragraph {Reporting} +LongBow functions and definitions for writing report libraries. +It uses the following header files: + +\begin{itemize} + \item {\bf longBow\_ReportANSITerminal\_Runtime.h} ANSI Terminal Reporting. +\item {\bf longBow\_Report\_Runtime.h} The LongBow Runtime Report Generator. +\item {\bf longBow\_Report\_Testing.h} The LongBow Test Report Generator. +\end{itemize} + + + \paragraph {Performance Testing} +Using LongBow for performance tests. + +\end{document} diff --git a/longbow/documentation/LaTeX Documentation/LongBow.tex b/longbow/documentation/LaTeX Documentation/LongBow.tex new file mode 100644 index 00000000..8f8a7e60 --- /dev/null +++ b/longbow/documentation/LaTeX Documentation/LongBow.tex @@ -0,0 +1,37 @@ +%---------------------------------------------------------------------------------------- +% PACKAGES AND OTHER DOCUMENT CONFIGURATIONS +%---------------------------------------------------------------------------------------- +\documentclass[fleqn,12pt]{PARCOneColumn} % Document font size and equations flushed left +% +%---------------------------------------------------------------------------------------- +% COLUMNS +%---------------------------------------------------------------------------------------- +% +\setlength{\columnsep}{0.55cm} % Distance between the two columns of text +\setlength{\fboxrule}{0.75pt} % Width of the border around the abstract +% +%---------------------------------------------------------------------------------------- +% HYPERLINKS +%---------------------------------------------------------------------------------------- +% +\definecolor{urlcolor}{RGB}{0,0,90} % Color of the article title and sections +\definecolor{citecolor}{RGB}{0,0,90} % Color of the article title and sections +\definecolor{linkcolor}{RGB}{0,0,90} % Color of the article title and sections +\usepackage{hyperref} % Required for hyperlinks +\hypersetup{hidelinks, +colorlinks, +breaklinks=true, +urlcolor=urlcolor, +citecolor=citecolor, +linkcolor=linkcolor, +bookmarksopen=false, +pdftitle={Title}, +pdfauthor={Author}} +% +\input{Packages} +% +\input{title} +% +\input{abstract} +% +\input{document} diff --git a/longbow/documentation/LaTeX Documentation/PARCOneColumn.cls b/longbow/documentation/LaTeX Documentation/PARCOneColumn.cls new file mode 100644 index 00000000..a58d3409 --- /dev/null +++ b/longbow/documentation/LaTeX Documentation/PARCOneColumn.cls @@ -0,0 +1,288 @@ +% A PARC specific refinement of: +% +% Stylish Article +% LaTeX Template +% Version 2.0 (13/4/14) +% +% Available from: +% http://www.LaTeXTemplates.com +% +% Original author: +% Mathias Legrand (legrand.mathias@gmail.com) +% +% License: +% CC BY-NC-SA 3.0 (http://creativecommons.org/licenses/by-nc-sa/3.0/) +% --------------------------------------------------------------------- +% Conference proceedings and article templates for +% personal open-archiving activities +% September 2012 +% --------------------------------------------------------------------- + +\NeedsTeXFormat{LaTeX2e} +\ProvidesClass{PARCOneColumn}[25/01/2012, v1.0] +\RequirePackage{ifthen} +\RequirePackage{calc} +\AtEndOfClass{\RequirePackage{microtype}} +\DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}} +\ProcessOptions* +\LoadClass{article} +\RequirePackage{ifpdf} % Needed to pick between latex and pdflatex + +%---------------------------------------------------------------------- +% FONTS +%---------------------------------------------------------------------- + +%\RequirePackage{times} % Loads the Times-Roman Fonts +\RequirePackage{palatino} % Loads the Palatino Fonts +%\RequirePackage{mathptmx} % Loads the Times-Roman Math Fonts + +%---------------------------------------------------------------------- +% VARIOUS USEFUL PACKAGES +%---------------------------------------------------------------------- + +\RequirePackage[utf8]{inputenc} +\RequirePackage{amsmath,amsfonts,amssymb} +\RequirePackage{graphicx,xcolor} +\RequirePackage[english]{babel} +\RequirePackage{booktabs} +\RequirePackage{multicol} +\RequirePackage{tabularx} + +%---------------------------------------------------------------------- +% MARGINS +%---------------------------------------------------------------------- + +\RequirePackage[left=2cm,% + right=2cm,% + top=2.25cm,% + bottom=2.25cm,% + headheight=11pt,% + letterpaper]{geometry}% + +%---------------------------------------------------------------------- +% FIGURES AND TABLES CAPTIONS +%---------------------------------------------------------------------- + +\RequirePackage[labelfont={bf,sf,small},% + labelsep=period,% + justification=raggedright]{caption} +\setlength{\abovecaptionskip}{0pt} +\setlength{\belowcaptionskip}{0pt} + +%---------------------------------------------------------------------- +% PARC Colors +%---------------------------------------------------------------------- + +\definecolor{PARCBlue}{RGB}{32,84,105} +\definecolor{PARCDarkBlue}{RGB}{0,35,50} +\definecolor{PARCLightBlue}{RGB}{58,110,143} +\definecolor{PARCOrange}{RGB}{255,102,0} +\definecolor{PARCLightGray}{RGB}{213,213,213} +\definecolor{PARCDarkGray}{RGB}{58,58,58} + +\definecolor{AbstractBackgroundColor}{RGB}{58,110,143} + +\definecolor{SectionColor}{RGB}{0,0,90} % Color of the article title and sections +% +%---------------------------------------------------------------------- +% PAGE HEADER +%---------------------------------------------------------------------- +% +\RequirePackage{fancyhdr} % Needed to define custom headers/footers +\headheight=13.6pt +\RequirePackage{lastpage} % Number of pages in the document +\pagestyle{fancy} % Enables the custom headers/footers +% Headers +\lhead{}% +\chead{}% +\rhead{\small\sffamily\bfseries\@PaperTitle\ --- \thepage/\pageref{LastPage}} +% Footers +\lfoot{\small\sffamily\bfseries\@LeftFooter}% +\cfoot{\small\sffamily\bfseries\@CenterFooter}% +\rfoot{\small\sffamily\bfseries\@RightFooter}% +\renewcommand{\headrulewidth}{0pt}% % No header rule +\renewcommand{\footrulewidth}{0pt}% % No footer rule + +%---------------------------------------------------------------------- +% SECTION/SUBSECTION/PARAGRAPH SET-UP +%---------------------------------------------------------------------- + +\RequirePackage[explicit]{titlesec} +\titleformat{\section} + {\color{PARCDarkBlue}\large\sffamily\bfseries} + {} + {0em} + {\colorbox{PARCDarkBlue!10}{\parbox{\dimexpr\linewidth-2\fboxsep\relax}{\centering\arabic{section}. #1}}} + [] +\titleformat{name=\section,numberless} + {\color{PARCDarkBlue}\large\sffamily\bfseries} + {} + {0em} + {\colorbox{PARCDarkBlue!10}{\parbox{\dimexpr\linewidth-2\fboxsep\relax}{\centering#1}}} + [] +\titleformat{\subsection} + {\color{PARCDarkBlue}\sffamily\bfseries} + {\thesubsection} + {0.5em} + {#1} + [] +\titleformat{\subsubsection} + {\sffamily\small\bfseries} + {\thesubsubsection} + {0.5em} + {#1} + [] +\titleformat{\paragraph}[runin] + {\sffamily\small\bfseries} + {} + {0em} + {#1} +\titlespacing*{\section}{0pc}{3ex \@plus4pt \@minus3pt}{5pt} +\titlespacing*{\subsection}{0pc}{2.5ex \@plus3pt \@minus2pt}{0pt} +\titlespacing*{\subsubsection}{0pc}{2ex \@plus2.5pt \@minus1.5pt}{0pt} +\titlespacing*{\paragraph}{0pc}{1.5ex \@plus2pt \@minus1pt}{10pt} + +%---------------------------------------------------------------------- +% TABLEOFCONTENTS SET-UP +%---------------------------------------------------------------------- +\newlength{\tocsep} +\setlength\tocsep{2em} % Sets the indentation of the sections in the table of contents +\setcounter{tocdepth}{3} % Three levels in the table of contents section: sections, subsections and subsubsections + +\usepackage{titletoc} +\contentsmargin{0cm} +\titlecontents{section}[\tocsep] + {\addvspace{4pt}\small\bfseries\sffamily} + {\contentslabel[\thecontentslabel]{\tocsep}} + {} + {\hfill\thecontentspage} + [] +\titlecontents{subsection}[\tocsep] + {\addvspace{2pt}\sffamily} + {\contentslabel[\thecontentslabel]{\tocsep}} + {} + {\ \titlerule*[.5pc]{.}\ \thecontentspage} + [] +\titlecontents*{subsubsection}[\tocsep] + {\footnotesize\sffamily} + {} + {} + {} + [\ \textbullet\ ] + +%---------------------------------------------------------------------- +% MULTIPLE AUTHOR SET +%---------------------------------------------------------------------- + +\newcount\@authcnt +\newcount\@tmpcnt\@tmpcnt\z@ + +\def\@affiliation{% + \ifnum\@tmpcnt<\@authcnt + \global\advance\@tmpcnt1 + \raggedright \csname @auth\romannumeral\the\@tmpcnt\endcsname\hfill\\% + \let\next\@affiliation \vskip1pt + \else + \let\next\relax + \fi +\next} + +\newcommand{\affiliation}[1]{% + \global\advance\@authcnt1 + \expandafter\gdef\csname @auth\romannumeral\the\@authcnt\endcsname + {#1}} + + +%---------------------------------------------------------------------- +% LIST CONTROL +%---------------------------------------------------------------------- + +\RequirePackage{enumitem} +%\setlist{nolistsep} % Uncomment to remove spacing between items in lists (enumerate, itemize) + +%---------------------------------------------------------------------- +% ABSTRACT+AUTHOR FRAME +%---------------------------------------------------------------------- + +\newcommand{\PaperTitle}[2]{\def\@PaperTitle{#1}\def\@PaperSubtitle{#2}} +\newcommand{\Archive}[1]{\def\@Archive{#1}} +\newcommand{\Authors}[1]{\def\@Authors{#1}} +\newcommand{\JournalInfo}[1]{\def\@JournalInfo{#1}} +\newcommand{\Abstract}[1]{\def\@Abstract{#1}} +\newcommand{\Keywords}[1]{\def\@Keywords{#1}} +\newcommand{\Masthead}[1]{\def\@Masthead{#1}} + +\newcommand{\LeftFooter}[1]{\def\@LeftFooter{#1}} +\newcommand{\CenterFooter}[1]{\def\@CenterFooter{#1}} +\newcommand{\RightFooter}[1]{\def\@RightFooter{#1}} + +\LeftFooter{} +\CenterFooter{} +\RightFooter{} +% +% --------------------------------------------------------------------- +% +\newcommand{\NormalSansBold}[1]{\normalsize\sffamily\bfseries #1} +\newcommand{\SmallSansBold}[1]{\small\sffamily\bfseries #1} +\newcommand{\MastHeadText}[1]{\sffamily\fontsize{10}{12}\selectfont #1} +% +\newcommand{\MakePARCMastHead}[1]{ +\setlength{\tabcolsep}{0pt} +\begin{tabular*}{\textwidth}{l @{\extracolsep{\fill}} p{0.618\textwidth} } + \includegraphics[width=110pt]{parc_black_solid}&\vbox{\raggedleft\MastHeadText{#1}\vskip0.24mm}\\ +\end{tabular*} +\vskip-5mm\hrule +} +% +\newcommand{\MakeTitle}[2]{% +{\raggedright\color{SectionColor}\sffamily\bfseries\fontsize{22}{25}\selectfont #1\par}% +{\raggedright\color{SectionColor}\sffamily\bfseries\fontsize{16}{24}\selectfont #2\par}% +} +% +\newcommand{\MakeAbstract}[2]{% +\parbox{\textwidth-6\fboxsep-2\fboxrule}{% +\ifx\@Keywords\@empty% +\sffamily\textbf{\abstractname}\\#1% +\else% +\sffamily\textbf{\abstractname}\\#1\\[4pt]% +\textbf{\keywordname}\\#2% +\fi% +}% +}% +% +\renewcommand{\@maketitle}{% +\centering{% +\thispagestyle{empty}% +\MakePARCMastHead{\@Masthead}% +\vskip30pt% +\MakeTitle{\@PaperTitle}{\@PaperSubtitle}% +\vskip10pt% +{\raggedright\color{SectionColor}\sffamily\fontsize{12}{16}\selectfont\@Authors\par}% +\vskip18pt% +\fcolorbox{SectionColor}{white}{% +\parbox{\textwidth-2\fboxsep-2\fboxrule}{\centering% +\colorbox{AbstractBackgroundColor!10}{% +\MakeAbstract{\@Abstract}{\@Keywords} +}% +\vskip4pt% +\begingroup% +\raggedright\sffamily\small% +\footnotesize\@affiliation\par% +\endgroup%% +}% +}% +\vskip25pt% +}% +}% +%---------------------------------------------------------------------- +% REFERENCES +%---------------------------------------------------------------------- + +% Remove brackets from numbering in List of References +\renewcommand{\@biblabel}[1]{\bfseries\color{SectionColor}\textsuperscript{[#1]}} +%\setlength{\bibitemsep}{0cm} +\let\oldbibliography\thebibliography +\renewcommand{\thebibliography}[1]{% +\addcontentsline{toc}{section}{\refname}% +\oldbibliography{#1}% +\setlength\itemsep{0pt}}% diff --git a/longbow/documentation/LaTeX Documentation/Packages.tex b/longbow/documentation/LaTeX Documentation/Packages.tex new file mode 100644 index 00000000..90f5f6db --- /dev/null +++ b/longbow/documentation/LaTeX Documentation/Packages.tex @@ -0,0 +1,58 @@ +% +% Specify packages that you need in this file. +% If a package requires configuration, do that here. +\usepackage{lipsum} +\usepackage{tcolorbox} + +\usepackage{listings} + +\definecolor{goodCodeColor}{rgb}{1.0,1.0,1.0} +\definecolor{badCodeColor}{rgb}{1.0,0.95,0.95} +\definecolor{mygreen}{rgb}{0,0.6,0} +\definecolor{mygray}{rgb}{0.5,0.5,0.5} +\definecolor{mymauve}{rgb}{0.58,0,0.82} +\lstset{ % + backgroundcolor=\color{goodCodeColor}, % choose the background color; you must add \usepackage{color} or \usepackage{xcolor} + basicstyle=\tt\small, % the size of the fonts that are used for the code + breakatwhitespace=false, % sets if automatic breaks should only happen at whitespace + breaklines=true, % sets automatic line breaking + captionpos=b, % sets the caption-position to bottom + commentstyle=\color{mygreen}, % comment style + deletekeywords={...}, % if you want to delete keywords from the given language + escapeinside={@}{@}, % if you want to add LaTeX within your code + extendedchars=true, % lets you use non-ASCII characters; for 8-bits encodings only, does not work with UTF-8 + frame=single, % adds a frame around the code + keepspaces=true, % keeps spaces in text, useful for keeping indentation of code (possibly needs columns=flexible) + keywordstyle=\color{blue}, % keyword style + language=C, % the language of the code + morekeywords={*,...}, % if you want to add more keywords to the set + numbers=left, % where to put the line-numbers; possible values are (none, left, right) + numbersep=5pt, % how far the line-numbers are from the code + numberstyle=\tiny\color{mygray}, % the style that is used for the line-numbers + rulecolor=\color{black}, % if not set, the frame-color may be changed on line-breaks within not-black text (e.g. comments (green here)) + showspaces=false, % show spaces everywhere adding particular underscores; it overrides 'showstringspaces' + showstringspaces=false, % underline spaces within strings only + showtabs=false, % show tabs within strings adding particular underscores + stepnumber=2, % the step between two line-numbers. If it's 1, each line will be numbered + stringstyle=\color{mymauve}, % string literal style + tabsize=2, % sets default tabsize to 2 spaces + title=\lstname % show the filename of files included with \lstinputlisting; also try caption instead of title +} + + +\newcommand{\functionBox}[1]{% + \begin{tcolorbox}[boxrule=0.5pt,arc=4pt,left=6pt,right=6pt,top=6pt,bottom=6pt,boxsep=0pt] + #1 + \end{tcolorbox}} + +\newcommand{\Returns}[2]{{\bf Returns:} #1\hfil\break\begin{tabular}{l r l} #2 \end{tabular}} +\newcommand{\retval}[2]{\hbox to1em{} & {#1} & {#2}\\ } + +\newcommand{\Cfunctionparam}[3]{\hbox to1em{} & #1 & {\tt #2} & #3 \\} +\newcommand{\paramdef}[1]{\begin{tabular}{ r r l l } #1\end{tabular}\hfil\break} +\newcommand{\Cfunctiondef}[3]{\functionBox{{#1} {\tt #2(}\hfil\break\paramdef{#3}{\tt )}}} + +\newcommand{\Cfunctionref}[1]{{\tt #1()}} +\newcommand{\functionAbstract}[1]{#1\hfil\break} +\newcommand{\functionReturns}[2]{{\bf Returns:}\hfil\break\indent\hbox to3em{} #1: #2\hfil\break} +\newcommand{\NULL}{{\tt NULL }} diff --git a/longbow/documentation/LaTeX Documentation/Title.tex b/longbow/documentation/LaTeX Documentation/Title.tex new file mode 100644 index 00000000..b05521b7 --- /dev/null +++ b/longbow/documentation/LaTeX Documentation/Title.tex @@ -0,0 +1,13 @@ +%---------------------------------------------------------------------------------------- +% ARTICLE INFORMATION +%---------------------------------------------------------------------------------------- +\Masthead{Networking and Distributed Systems\\Computing Science Laboratory\\Copyright 2014} + +\PaperTitle{LongBow}{Write Better C Programs} % Article title + +\Authors{Glenn Scott\textsuperscript{1}*} % Authors +\affiliation{\textsuperscript{1}\textit{Computing Science Laboratory, PARC}} % Author affiliation +\affiliation{*\textbf{Corresponding author}: glenn.scott@parc.com} % Corresponding author + +\Keywords{Software Development --- Software Testing} % Keywords - if you don't want any simply remove all the text between the curly brackets +\newcommand{\keywordname}{Keywords} % Defines the keywords heading name diff --git a/longbow/documentation/LaTeX Documentation/old/Longbow_documentation.tex b/longbow/documentation/LaTeX Documentation/old/Longbow_documentation.tex new file mode 100644 index 00000000..5db370c2 --- /dev/null +++ b/longbow/documentation/LaTeX Documentation/old/Longbow_documentation.tex @@ -0,0 +1,769 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Simple Sectioned Essay Template +% LaTeX Template +% +% This template has been downloaded from: +% http://www.latextemplates.com +% +% Note: +% The \lipsum[#] commands throughout this template generate dummy text +% to fill the template out. These commands should all be removed when +% writing essay content. +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +%---------------------------------------------------------------------------------------- +% PACKAGES AND OTHER DOCUMENT CONFIGURATIONS +%---------------------------------------------------------------------------------------- + +\documentclass[12pt]{article} % Default font size is 12pt, it can be changed here + +\usepackage{graphicx} % Required for including pictures + +\usepackage{float} % Allows putting an [H] in \begin{figure} to specify the exact location of the figure +\usepackage{wrapfig} % Allows in-line images such as the example fish picture + +\usepackage{lipsum} % Required to insert dummy text +\usepackage{hyperref} + +\usepackage{wrapfig} +\usepackage[toc]{appendix} +\usepackage{url} +\usepackage{mdframed} +\usepackage{listings} +\lstset{ % +basicstyle=\tt\footnotesize, +breakatwhitespace=false, + breaklines=true. + tabsize=4 +} + +\usepackage{float} +\restylefloat{table} + + +\linespread{1.2} % Line spacing + +%\setlength\parindent{0pt} % Uncomment to remove all indentation from paragraphs + +\graphicspath{{Pictures/}} % Specifies the directory where pictures are stored + +\begin{document} + +%---------------------------------------------------------------------------------------- +% TITLE PAGE +%---------------------------------------------------------------------------------------- +\begin{titlepage} + +\newcommand{\HRule}{\rule{\linewidth}{0.5mm}} % Defines a new command for the horizontal lines, change thickness here + +\center % Center everything on the page + + +\HRule \\[0.4cm] +{ \huge \bfseries Longbow Documentation}\\[0.4cm] % Title of your document +\HRule \\[1.5cm] + +\begin{minipage}{0.4\textwidth} +\begin{flushleft} \large +\emph{Author:}\\ +Glenn \textsc{Scott} % Your name +\end{flushleft} +\end{minipage} +~ + +{\large \today}\\[3cm] % Date, change the \today to a set date if you want to be precise + +%\includegraphics{Logo}\\[1cm] % Include a department/university logo - this will require the graphicx package + +\vfill % Fill the rest of the page with whitespace + +\end{titlepage} + +%---------------------------------------------------------------------------------------- +% TABLE OF CONTENTS +%---------------------------------------------------------------------------------------- + +\tableofcontents % Include a table of contents +\newpage +\section{Overview} % The \section{} command stops section numbering + +LongBow is software to help you write better C programs. It provides: +\begin{itemize} +\item a run-time assertion facility to establish strict rules on the state of your program. +\item a testing facility based on the xUnit testing model. +\item compile-time assistance for writing code meant to be compiled by compilers with different features. +\end{itemize} + +LongBow can help you find and manage problems early, establish and maintain confidence in the correctness of your code, make collaboration easier, facilitate future change, and improve overall design. + +LongBow allows you to take control and establish invariant pre- and post-conditions that detect inconsistencies and unexpected results in your programs in order to find bugs and design deficiencies in the code during development rather than waiting for others to find your bugs for you. + +\section{Set up and installation} +How to install, configure, link, and run LongBow. +\subsection {Installation} +Get the tar file from xxx. +untar and do a make install. +The resulting LongBow directory will contain the C header files, C source files, and runtime libraries needed. + +\subsection {Configuration} + +\subsubsection{LongBow with LLDB} +The {\tt lldb} debugger is aware when C files are included. This induces a problem where the breakpoints in the included files are not set. But you can configure lldb to set them: In ~/.lldbinit settings set target.inline-breakpoint-strategy always + + +\hfill \texttt{settings set target.inline-breakpoint-strategy always} \hfill \break + +\subsubsection{LongBow with GDB} +LongBow uses signals to interrupt program flow when an assertion fails. When using gdb this will cause gdb to stop running of the test. This probably isn?t what you want and would rather prefer that gdb just ignore the signal and let the LongBow unit test signal handler take care of the signal. To do this, you must configure gdb to ignore the signal and to allow it to pass to the program being executed. + + +\hfill \texttt{handle 6 nostop pass} \hfill \break + +\subsubsection{Linking and Libraries} +There are two LongBow libraries that must be linked with the application: the primary LongBow library, (\url{liblongbow.a}) and one of the LongBow reporter libraries. The reporter libraries enable the reporting mechanism for Longbow. Currently two reporter libraries have been implemented: \url{liblongbow-plaintext.a} which displays output as simple text; and \url{liblongbow-ansiterm.a} which displays output as an ANSI colorized output. Both display to standard output. + +\subsubsection{Running and Runtime Behavior} +You can "run" Longbow in one of two ways: you can run your application with assertions turned on in order to test expected invariance during runtime; or you can run your tests using Longbow's Test Runner. Turning off assertions for runtime is not currently supported. + +\section{Programming with Assertions} + + Longbow's Assertions offer a way to check runtime invariance throughout your program. Traps are a subset of Assertions that are executed at runtime even if Assertions have been turned off during deployment. They should be used when program failure is the correct response to assertion failure. + +The assertion framework is based on the following design principles: +\begin{itemize} +\item It is intentionally simple and can be extended. +\item You don't have to change your program design to accommodate assertions. +\item It is designed specifically for C programs. +\item It is based on programming with invariance. +\item Assertions may be used only during development as a debugging aid, or in deployment as well to offer more descriptive errors to users. +\end{itemize} + + +\subsection{Designing with Assertions } +Assertions can be used to debug code and give better information about errors to users. They should not be used for error handling. Assertions should be used to explicitly test for conditions that must be true in order for an operation to work. Examples include testing for NULL pointers, out-of-bounds array indices, and incorrect dependent relationships. Ultimately your code should work every time under all input conditions without ever triggering an assertion although passing tests don't guarantee proper design. You should aim for 100\% code coverage. + +Be strategic about where the assertions are located and what they test for. +A failed assertion should be considered a bug should be treated as such. For example a failure to open a file is likely not a bug in your program, per se, but indicative of some other problem and programmatic error handling would probably be the best approach to handling the missing file. + +Assertions can be included or excluded at compile-time. In many cases, it is reasonable to keep the assertions in production releases as an aid to future bug reporting. + +\subsection{Using the Assertion Libraries } + +LongBow provides a basic set of assertions that test a condition and trigger the assertion if the condition fails to be true. When an assertion triggers the following occurs: +\begin{itemize} +\item An Event is created which records the kind of assertion that failed and the location of the assertion's failure. +\item The formatted message of the failed assertion is reported via the LongBow report library. +\item The running program is sent a SIGABRT signal. +\end{itemize} + +The following four assertions are currently supported: +\begin{itemize} +\item assertTrue +\item assertFalse +\item assertNull +\item assertNotNull +\end{itemize} + +The function signatures are: + +\hfill \texttt{void assertX(condition, "\_\_\_",...);} \hfill \break +where "\_\_\_" is the printf null-terminated C-String that will be displayed when the assertion triggers. The ... represents the arguments that might be used to create the string. + +There are two basic C header files that are needed: +\begin{itemize} +\item \textbf{LongBow/runtime.h} is the basic header file needed for assertions and testing. +\item \textbf{LongBow/compiling.h} is used when you have code that needs to work across multiple compilers. +\end{itemize} + +\subsection {Using Traps} +LongBow traps are subsets of assertions and are intended for simple error reporting. There is no functional difference between a trap and an assertion, however, Traps cannot be shut off during runtime so they are good to use for deployment if you plan to turn assertions off and the program should terminate when the assertion is not met. + +Traps take as arguments a condition and a printf(3) format string of explanatory text along with any required values. A typical trap is called with: + +{\tt trap (condition, ...) } + +where {\tt ...} is the printf format string and values. + +\noindent Currently supported traps are defined in \texttt{traps.h} and include: +\begin{itemize} +\item \textbf{trapIllegalValue:} Used for capturing failed parameter validation, for example. +\item \textbf{trapIllegalValueIf:} Used to trap an illegal value if a condition is met. +\item \textbf{trapNotImplemented:} Used to report and abort an unimplemented capability. +\item \textbf{trapOutOfBounds:} Used to trap an out-of-bounds condition on an index. +\item \textbf{trapOutOfBoundsIf:} Used to trap an out-of-bounds condition for a specific value. +\item \textbf{trapOutOfMemory:} Used to signal that no more memory can be allocated. +\item \textbf{trapUnexpectedState:} Used to signal that an unexpected or inconsistent state was encountered. +\item \textbf{trapUnexpectedStateIf:} If the given condition is true, used to signal that an unexpected state was encountered. +\item \textbf{trapUnrecoverableState:} Used to report an unrecoverable state in program execution. +\end{itemize} + + + + +\subsection{Examples } + +\paragraph {assertNotNull example} +\paragraph {assertNotNull example} + +\begin{lstlisting} +#include <LongBow/assertions> +#include <unistd.h> +#include <string.h> + +void +function(char *pointer) +{ + assertNotNull(pointer, "The pointer cannot be NULL."); + + write(1, pointer, strlen(pointer)); +} + +int +main(int argc, char *argv[]) +{ + function(0); +} +\end{lstlisting} + + +In this case the assertNotNull will trigger and the program will immediately terminate with the following output: + +\begin{lstlisting} +Assert pointer.c:8 function() pointer != NULL The pointer cannot be NULL. +0 pointer 0x0000000107840d4c function + 188 +1 pointer 0x0000000107840dd1 main + 33 +2 libdyld.dylib 0x00007fff887595fd start + 1 + +\end{lstlisting} + +\paragraph {assertTrue example} + \paragraph {assertTrue example} + + \begin{lstlisting} + LONGBOW_TEST_CASE(Global, myTest) +{ + struct timeval timeval; + timeval.tv_sec = 0; + timeval.tv_usec = 1000; + + char *expected = "0.001000"; + char *actual = parcTime\_FormatTimeval(timeval); + assertTrue(strcmp(expected, actual) == 0, "Expected \%s, actual \%s", expected, actual); + parc_free(actual); +} + \end{lstlisting} + +\paragraph {Example using assertNull, assertNotNull, and assertTrue} + \paragraph {Example using assertNull, assertNotNull, and assertTrue} + + \begin{lstlisting} + static void +parcDeque_AssertInvariants(const PARCDeque *deque) +{ + assertNotNull(deque, "Parameter cannot be null."); + if (deque->head != NULL) { + assertTrue(deque->size != 0, "PARCDeque head is not-null, but size is zero."); + assertNotNull(deque->tail, "PARCDeque head is not-null, but tail is null."); + parcDequeNode_AssertInvariants(deque->head); + parcDequeNode_AssertInvariants(deque->tail); + } else { + assertNull(deque->tail, "PARCDeque head is null, but tail is not null."); + assertTrue(deque->size == 0, "PARCDeque head is null, but size is not zero."); + } +} + +\end{lstlisting} + +\paragraph {assertFalse example} +\paragraph {assertFalse example} + \begin{lstlisting} +RtaCommand * +rtaCommand_Read(int fd) +{ + ssize_t readlen; + uint32_t netbyteorder; + size_t len; + char *p; + RtaCommand *command; + + readlen = read(fd, &netbyteorder, 4); + assertFalse(readlen < 0, "socket read error: %s\n", strerror(errno)); + assertTrue(readlen == 4, "Partial read on command length"); + + len = ntohl(netbyteorder); + p = parc_malloc(len); + readlen = read(fd, p, len); + assertTrue(readlen == len, "Partial read on command"); + + command = rtaCommand_Parse(p); + parc_free(p); + return command; +} +\end{lstlisting} + + +\section{Unit testing} +Longbow provides an xUnit-style unit testing framework. The framework is a mechanism for organizing and running trees of test code. It is organized hierarchically into three components: a Test Runner, Test Fixtures, and Test Cases. + +A Test Runner file is associated 1:1 with a C source file, with the word "test\_" prepended on the C source file name. For example, the Test Runner file for parc\_Buffer.c would be test\_parc\_Buffer.c. This file contains all of the Test Fixtures and Test Cases needed to test the associated C source file. + + Each Test Runner will run a set of Test Fixtures. Test Fixtures are an organizational unit that allows you to group your Test Cases. The grouping may be done by functionality, by static vs non static functions, or by any other organizing principle that you choose. + + A Test Fixture runs a set of Test Cases each of which is responsible for testing some aspect of the C module. + +Tests are run in the order they are defined. The Test Runner will start with Test Fixture1 and all of its Test Cases, move on to Test Fixture2 and its Test Cases etc. Tests should be idempotent, however, and not assume any particular order or be dependent on each other. They should not leave state such that the next Test Case inherits that state. + +\subsection{Designing tests } +\textcolor{red}{Put something here} + +\subsection{Writing tests with the Test Runner module } +\subsubsection{Test Runners} +A Test Runner is the top-level executable unit in a test. It is responsible for establishing the necessary state for the set of tests it contains, executing the tests via Test Fixtures and Test Cases, and tearing down state when the tests have completed. + +A Test Runner requires the following header files: +\begin{itemize} +\item \textbf{LongBow/runtime.h} is the basic header file needed for assertions and testing. +\item \textbf{LongBow/unit-test.h} is the basic header file needed for testing. +\item \textbf{LongBow/compiling.h} is used when you have code that needs to work across multiple compilers - it contains the matrix of compiler and / you are using. +\end{itemize} + +\noindent The source code of a Test Runner has the following basic structure: + +\begin{lstlisting} +#include <LongBow/testing.h> + +LONGBOW_TEST_RUNNER(myRunner) +{ +} + +LONGBOW_TEST_RUNNER_SETUP(myRunner) +{ + // Code to set up required state + return LONGBOW_STATUS_SUCCEEDED; +} + +LONGBOW_TEST_RUNNER_TEARDOWN(myRunner) +{ + //Code to clean up state + return LONGBOW_STATUS_SUCCEEDED; +} + +\end{lstlisting} + + +Each of these functions has a local variable - {\tt LongBowRunner *testRunner} - which may be used to manipulate the clipboard (as an example). The Text Fixtures and Test Cases launched by the Test Runner will have access to this variable as well as their own local variable. Thus a Test Fixture will have access to the {\tt testRunner} that is passed to it as well as its own {\tt LongBowFixture *testFixture} and a Test Case will have access to {\tt testRunner, testFixture} and its own {\tt LongBowCase *testCase}. + +\subsubsection{Test Fixtures} + + +A Test Fixture is a subcomponent which has the same structure as a Test Runner. The following code adds Test Fixture to a Test Runner: + +\begin{lstlisting} +LONGBOW_TEST_RUNNER(myRunner) +{ + LONGBOW_RUN_TEST_FIXTURE(Global); + LONGBOW_RUN_TEST_FIXTURE(Local); +} +\end{lstlisting} + + +Like the Test Runner, it is responsible for setting up and tearing down state needed by the Test Cases. + +\begin{lstlisting} + +LONGBOW_TEST_FIXTURE(Global) +{ + LONGBOW_RUN_TEST_CASE(Global, myTest); +} + +LONGBOW_TEST_FIXTURE_SETUP(Global) +{ + return LONGBOW_STATUS_SUCCEEDED; +} + +LONGBOW_TEST_FIXTURE_TEARDOWN(Global) +{ + return LONGBOW_STATUS_SUCCEEDED; +} +\end{lstlisting} + +\subsubsection{Test Cases} +Test Cases are the leaf nodes of the testing tree. Each Test Case tests one aspect of the C module. + +\paragraph {Handling Test Case state safely} + +Every Test Case has access to a private \"clipboard\" that contains data shared between the Test Case and the set up and teardown functions of its encapsulating Test Fixture. This shared state is used to provide specific environment or initialized variables for the test and for the test to communicate specialized information to the teardown function. + +For example, a Test Case which is expected to fail as the result of testing a failure condition might exit without releasing resources which are left in an unsafe state. As multiple tests may be run in one process, it is important to clean these up before launching the next test. + +The following example demonstrates the clipboard mechanism: +\begin{itemize} +\item{The Test Fixture setup function allocates the necessary resources and puts references to them into the clipboard.} +\item{The Test Case gets these references, uses them, and fails.} +\item{The Test Fixture tear-down function obtains the resources from the clipboard and deallocates them.} +\end{itemize} + +\subsubsection {Test Runner Example} +\noindent The following is an example of a test file : + +\begin{lstlisting} +#include <stdio.h> +#include <string.h> + +#include <LongBow/testing.h> +#include <LongBow/debugging.h> + +LONGBOW_TEST_RUNNER(testClipboard) +{ + LONGBOW_RUN_TEST_FIXTURE(Global); +} + +LONGBOW_TEST_RUNNER_SETUP(testClipboard) +{ + return LONGBOW_STATUS_SUCCEEDED; +} + +LONGBOW_TEST_RUNNER_TEARDOWN(testClipboard) +{ + return LONGBOW_STATUS_SUCCEEDED; +} + +LONGBOW_TEST_FIXTURE(Global) +{ + LONGBOW_RUN_TEST_CASE(Global, testClipboard); +} + +LONGBOW_TEST_FIXTURE_SETUP(Global) +{ + char *testData = strdup("Hello World"); + longBowTest Case_SetClipBoardData(testCase, testData, free); + + return LONGBOW_STATUS_SUCCEEDED; +} + +LONGBOW_TEST_FIXTURE_TEARDOWN(Global) +{ + return LONGBOW_STATUS_SUCCEEDED; +} + +LONGBOW_TEST_CASE(Global, testClipboard) +{ + char *testData = longBowTest Case_GetClipBoardData(testCase); + printf("Shared state '%s'\n", testData); +} + +int +main(int argc, char *argv[]) +{ + LongBowRunner *testRunner = LONGBOW_TEST_RUNNER_CREATE(testClipboard); + int exitStatus = LONGBOW_TEST_MAIN(argc, argv, testRunner); + longBowTest Runner_Destroy(&testRunner); + exit(exitStatus); +} +\end{lstlisting} + +\subsubsection {Testing for Successful Failure} +Testing for success is straightforward but we also may have to test that something fails when it is supposed to. +This section describes how to test for an expected non-success result. + +To compose a Test Case that expects a result other than success, use the {\tt LONGBOW\_TEST\_CASE\_EXPECTS} function which takes the expected event as a parameter and completes. The example below shows the capture of a successful segmentation fault. + + +\begin{lstlisting} +#include <stdio.h> +#include <sys/types.h> +#include <signal.h> + +#include <LongBow/unit-test.h> + +LONGBOW_TEST_RUNNER(LongBow) +{ + LONGBOW_RUN_TEST_FIXTURE(MyFixture); +} + +LONGBOW_TEST_RUNNER_SETUP(LongBow) +{ + return LONGBOW_STATUS_SUCCEEDED; +} + +LONGBOW_TEST_RUNNER_TEARDOWN(LongBow) +{ + return LONGBOW_STATUS_SUCCEEDED; +} + +LONGBOW_TEST_FIXTURE(MyFixture) +{ + LONGBOW_RUN_TEST_CASE(MyFixture, alwaysSEGV); +} + +LONGBOW_TEST_FIXTURE_SETUP(MyFixture) +{ + return LONGBOW_STATUS_SUCCEEDED; +} + +LONGBOW_TEST_FIXTURE_TEARDOWN(MyFixture) +{ + return LONGBOW_STATUS_SUCCEEDED; +} + +LONGBOW_TEST_CASE_EXPECTS(MyFixture, alwaysSEGV, .event = &LongBowEventSIGSEGV) +{ + int *p = 0; + int i = *p; +} + +int +main(int argc, char *argv[]) +{ + LongBowRunner *testRunner = LONGBOW_TEST_RUNNER_CREATE(LongBow); + int status = LONGBOW_TEST_MAIN(argc, argv, testRunner, NULL); + longBowTest Runner_Destroy(&testRunner); + + exit(status); +} + +\end{lstlisting} + +\subsection{Running tests} + +The overall process for writing and running your tests: +\begin{itemize} +\item Write a Test Runner file for every .c file that completely tests all of the code container in the .c file. This filename should be "test\_" prepended to the name of the file you are testing. +\item Compile the Test Runner file with one of: +\begin {itemize} +\item -llongbow -llongbow-ansiterm +\item -llongbow -llongbow-textplain +\end{itemize} +\item Execute the Test Runner. +\end{itemize} + + +\subsection{Examples } + +Here is an example of a C source file and its associated Test file. Tutorial.c is a small C program which simply provides an uninteresting but useful exemplar of the test framework. + + +\noindent \textbf{Tutorial.c} + +\begin{lstlisting} +#include <unistd.h> +#include <stdbool.h> +#include <signal.h> + +static bool +_privateFunction() +{ + return true; +} + +bool +alwaysSucceed() +{ + return _privateFunction(); +} + +bool +alwaysFail() +{ + return false; +} + +bool +blowUp() +{ + char *p = 0; + *p = 0; + + return true; +} + +\end{lstlisting} + +The following code is the test file for the Tutorial.c. Note that the file name is simply the C source file name with "test\_" prepended. In this example, the Test Runner divides the Test Cases into two Test Fixtures: one to focus on the Static functions and one to focus on the Global functions. + +\noindent \textbf{test\_Tutorial.c} +\begin{lstlisting} + +#include "tutorial.c" + +#include <LongBow/unit-test.h> + + +LONGBOW_TEST_RUNNER(myTutorialTest) +{ + LONGBOW_RUN_TEST_FIXTURE(Static); + LONGBOW_RUN_TEST_FIXTURE(Global); +} + +LONGBOW_TEST_RUNNER_SETUP(myTutorialTest) +{ + return LONGBOW_STATUS_SUCCEEDED; +} + +LONGBOW_TEST_RUNNER_TEARDOWN(myTutorialTest) +{ + return LONGBOW_STATUS_SUCCEEDED; +} + +LONGBOW_TEST_FIXTURE(Global) +{ + LONGBOW_RUN_TEST_CASE(Global, alwaysSucceed); + LONGBOW_RUN_TEST_CASE(Global, alwaysFail); + LONGBOW_RUN_TEST_CASE(Global, blowUp); + +} + +LONGBOW_TEST_FIXTURE_SETUP(Global) +{ + return LONGBOW_STATUS_SUCCEEDED; +} + +LONGBOW_TEST_FIXTURE_TEARDOWN(Global) +{ + return LONGBOW_STATUS_SUCCEEDED; +} + +LONGBOW_TEST_CASE(Global, alwaysSucceed) +{ + bool result = alwaysSucceed(); + + assertTrue(result, "This test must always succeed."); +} + +LONGBOW_TEST_CASE(Global, alwaysFail) +{ + bool result = alwaysFail(); + + assertTrue(result, "This test will fail."); +} + +LONGBOW_TEST_CASE_EXPECTS(Global, blowUp, .event = &LongBowEventSIGSEGV) +{ + blowUp(); + + assertTrue(false, "This will not be executed"); +} + + +LONGBOW_TEST_FIXTURE(Static) +{ + LONGBOW_RUN_TEST_CASE(Static, _privateFunction); +} + +LONGBOW_TEST_FIXTURE_SETUP(Static) +{ + return LONGBOW_STATUS_SUCCEEDED; +} + +LONGBOW_TEST_FIXTURE_TEARDOWN(Static) +{ + return LONGBOW_STATUS_SUCCEEDED; +} + +LONGBOW_TEST_CASE(Static, _privateFunction) +{ + bool result = _privateFunction(); + + assertTrue(result, "This test must always succeed."); +} + +int +main(int argc, char *argv[argc]) +{ + LongBowRunner *testRunner = LONGBOW_TEST_RUNNER_CREATE(myTutorialTest); + int status = LONGBOW_TEST_MAIN(argc, argv, testRunner); + + longBowTest Runner_Destroy(&testRunner); + exit(status); +} + +\end{lstlisting} + +\section {Compiling and Compiler Support} +LongBow consolidates a variety of compile-time options that you include in your code. + +For example, the C99 standard defines the pragma operator and various compilers support this in various ways. + +\section{The LongBow Reporter} +The Longbow reporter offers a more user-friendly option for viewing the output of the running tests. In addition to linking with the primary LongBow library ({\tt liblongbow.a}), you also need to link with one of the following reporting libraries to control presentation of the test output. +\begin{itemize} +\item {\bf liblongbow-ansiterm.a} This option produces output that is color coded to indicate the degree of success: green for a successful test; yellow for warnings; and red for failure. +\item {\bf liblongbow-plaintext.a} This option produces plain text output. +\item {\bf liblongbow-json.a} This option is in development and will produce output in JSON format. +\end{itemize} + + + +\section {Appendices} +\subsection {Function Documentation} +The following modules are included in LongBow: +\begin {itemize} +\item \textbf{Runtime:} LongBow functions and macros for runtime. +\item \textbf{Testing:} LongBow functions and macros for writing tests. +\item \textbf{Internals:} LongBow functions and macros used internally. +\item \textbf{Reporting:} LongBow functions and definitions for writing report libraries. +\item \textbf{Performance testing:} LongBow functions and definitions for writing performance tests. +\end{itemize} + +\paragraph {Runtime} +LongBow runtime support consists primarily of assertions and traps. Developers insert assertions to insist that certain conditions are true before permitting the program to continue. If the assertion fails, the program is abnormally terminated. It uses the following files: + +\begin{itemize} +\item {\bf assertions.h:} Runtime and Test Assertions. + \item {\bf longBow\_EventType.h:} LongBow Events and Support. + \item {\bf longBow\_Runtime.h:} The LongBow Runtime support. + \item {\bf runtime.h:} LongBow Runtime Support. + \item {\bf traps.h:} Runtime and Test Traps. +\end{itemize} + + +\paragraph {Testing} +LongBow testing support consists of macros and ancillary functions to implement an xUnit style of writing and running tests. Test writers create a LONGBOW\_TEST\_RUNNER function which invokes one or more LONGBOW\_TEST\_FIXTURE functions, each of which invoke a specific LONGBOW\_TEST\_CASE. It uses the following files: + +\begin{itemize} +\item {\bf longBow\_EventType.h:} LongBow Events and Support. + \item {\bf longBow\_Main.h:} A main() function to run one or more LongBow Test Runners. + \item {\bf longBow\_OpenFile.h:} LongBow support for files and file descriptors. + \item {\bf longBow\_Runner.h:} LongBow Test Runner Support. + \item {\bf longBow\_Status.h} A simple status representation for a LongBow Test Case. + \item {\bf longBow\_Test CaseClipBoard.h:} LongBow Clipboard shared between the setup, test case, and teardown. + \item {\bf longBow\_UnitTesting.h} Unit Testing Support. . + \item {\bf testing.h:} LongBow testing functionality. + \item {\bf unit-test.h} LongBow Unit Test Support. +\end{itemize} + +\paragraph {Internals} +LongBow functions and macros used internally. +It uses the following files: + +\begin{itemize} + \item {\bf longBow\_ArrayList.h} A simple, list implementation using a dynamic array. + \item {\bf longBow\_Backtrace.h} Support for Stack Traces. + \item {\bf longBow\_Configuration.h} Support for LongBow Configuration. + \item {\bf longBow\_Debugging.h} Support for LongBow and Application Debugging. + \item {\bf longBow\_Event.h} LongBow Event Support. + \item {\bf longBow\_EventType.h} LongBow Events and Support. + \item {\bf longBow\_Fixture.h} Manage the execution of Test Cases. + \item {\bf longBow\_Location.h} LongBow Source File Location. + \item {\bf longBow\_Test Case.h} The interface and supporting functionality of a LongBow Test Case. + \item {\bf longBow\_Test CaseResult.h} LongBow Test Case Results. +\end{itemize} + + + \paragraph {Reporting} +LongBow functions and definitions for writing report libraries. +It uses the following header files: + +\begin{itemize} + \item {\bf longBow\_ReportANSITerminal\_Runtime.h} ANSI Terminal Reporting. +\item {\bf longBow\_Report\_Runtime.h} The LongBow Runtime Report Generator. +\item {\bf longBow\_Report\_Testing.h} The LongBow Test Report Generator. +\end{itemize} + + + \paragraph {Performance Testing} +Using LongBow for performance tests. + + +\end{document}
\ No newline at end of file diff --git a/longbow/documentation/LaTeX Documentation/old/SelfArx2.cls b/longbow/documentation/LaTeX Documentation/old/SelfArx2.cls new file mode 100755 index 00000000..704a5e6e --- /dev/null +++ b/longbow/documentation/LaTeX Documentation/old/SelfArx2.cls @@ -0,0 +1,191 @@ +% --------------------------------------------------------------------- +% Conference proceedings and article templates for +% personal open-archiving activities +% September 2012 +% +% 4/16/14 Marc Mosko - changed \arabic{section} to just {\thesection} so appendix prints as "A", etc. +% 4/16/14 Marc Mosko - Changes how package xcolor is loaded so it has the "table" option +% +% --------------------------------------------------------------------- + +\NeedsTeXFormat{LaTeX2e} +\ProvidesClass{SelfArx}[25/01/2012, v1.0] +\RequirePackage{ifthen} +\RequirePackage{calc} +\AtEndOfClass{\RequirePackage{microtype}} +\DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}} +\ProcessOptions* +\LoadClass{article} + +\RequirePackage{times} % Loads the Times-Roman Fonts +\RequirePackage{mathptmx} % Loads the Times-Roman Math Fonts +\RequirePackage{ifpdf} % Needed to pick between latex and pdflatex + +% --------------------------------------------------------------------- +\RequirePackage[utf8]{inputenc} +\RequirePackage{amsmath,amsfonts,amssymb} +\RequirePackage{graphicx} +\RequirePackage[table]{xcolor} +\RequirePackage[english]{babel} +\RequirePackage{booktabs} +% --------------------------------------------------------------------- + +%%%%% for abstract+authors frames + + +% --------------------------------------------------------------------- +% margins +\RequirePackage[left=2cm,% + right=2cm,% + top=2.25cm,% + bottom=2.25cm,% + headheight=11pt,% + letterpaper]{geometry}% +\RequirePackage[labelfont={bf,sf},% + labelsep=period,% + justification=raggedright]{caption} +% --------------------------------------------------------------------- +\RequirePackage{fancyhdr} % Needed to define custom headers/footers +\RequirePackage{lastpage} % Number of pages in the document +\pagestyle{fancy} % Enables the custom headers/footers +% Headers +\lhead{}% +\chead{}% +\rhead{\small\sffamily\bfseries\@PaperTitle\ --- \thepage/\pageref{LastPage}} +% Footers +\lfoot{}% +\cfoot{}% +\rfoot{}% +\renewcommand{\headrulewidth}{0pt}% % No header rule +\renewcommand{\footrulewidth}{0pt}% % No footer rule +% --------------------------------------------------------------------- +% section/subsection/paragraph set-up +\RequirePackage[explicit]{titlesec} +\titleformat{\section} + {\color{color1}\large\sffamily\bfseries} + {} + {0em} + {\colorbox{color2!10}{\parbox{\dimexpr\linewidth-2\fboxsep\relax}{\centering{\thesection}. #1}}} + [] +\titleformat{name=\section,numberless} + {\color{color1}\large\sffamily\bfseries} + {} + {0em} + {\colorbox{color2!10}{\parbox{\dimexpr\linewidth-2\fboxsep\relax}{\centering#1}}} + [] +\titleformat{\subsection} + {\color{color1}\sffamily\bfseries} + {\thesubsection} + {0.5em} + {#1} + [] +\titleformat{\subsubsection} + {\sffamily\small\bfseries} + {\thesubsubsection} + {0.5em} + {#1} + [] +\titleformat{\paragraph}[runin] + {\sffamily\small\bfseries} + {} + {0em} + {#1} +\titlespacing*{\section}{0pc}{3ex \@plus4pt \@minus3pt}{5pt} +\titlespacing*{\subsection}{0pc}{2.5ex \@plus3pt \@minus2pt}{0pt} +\titlespacing*{\subsubsection}{0pc}{2ex \@plus2.5pt \@minus1.5pt}{0pt} +\titlespacing*{\paragraph}{0pc}{1.5ex \@plus2pt \@minus1pt}{10pt} +% --------------------------------------------------------------------- +% tableofcontents set-up +\usepackage{titletoc} +\contentsmargin{0cm} +\titlecontents{section}[\tocsep] + {\addvspace{4pt}\small\bfseries\sffamily} + {\contentslabel[\thecontentslabel]{\tocsep}} + {} + {\hfill\thecontentspage} + [] +\titlecontents{subsection}[\tocsep] + {\addvspace{2pt}\small\sffamily} + {\contentslabel[\thecontentslabel]{\tocsep}} + {} + {\ \titlerule*[.5pc]{.}\ \thecontentspage} + [] +\titlecontents*{subsubsection}[\tocsep] + {\footnotesize\sffamily} + {} + {} + {} + [\ \textbullet\ ] +% --------------------------------------------------------------------- +% Get the multiple author set +\newcount\@authcnt +\newcount\@tmpcnt\@tmpcnt\z@ + +\def\@affiliation{% + \ifnum\@tmpcnt<\@authcnt + \global\advance\@tmpcnt1 + \raggedright \csname @auth\romannumeral\the\@tmpcnt\endcsname\hfill\\% + \let\next\@affiliation \vskip1pt + \else + \let\next\relax + \fi +\next} + +\newcommand{\affiliation}[1]{% + \global\advance\@authcnt1 + \expandafter\gdef\csname @auth\romannumeral\the\@authcnt\endcsname + {#1}} +% --------------------------------------------------------------------- +\RequirePackage{enumitem} +%\setlist{nolistsep} % Uncomment to remove spacing between items in lists (enumerate, itemize) +% --------------------------------------------------------------------- +% Remove brackets from numbering in List of References +\renewcommand{\@biblabel}[1]{\bfseries\color{color1}\textsuperscript{[#1]}} +%\setlength{\bibitemsep}{0cm} +% --------------------------------------------------------------------- +\newcommand{\PaperTitle}[1]{\def\@PaperTitle{#1}} +\newcommand{\Archive}[1]{\def\@Archive{#1}} +\newcommand{\Authors}[1]{\def\@Authors{#1}} +\newcommand{\JournalInfo}[1]{\def\@JournalInfo{#1}} +\newcommand{\Abstract}[1]{\def\@Abstract{#1}} +\newcommand{\Keywords}[1]{\def\@Keywords{#1}} +% --------------------------------------------------------------------- +\renewcommand{\@maketitle}{% +\twocolumn[{% +\thispagestyle{empty}% +\vskip-36pt% +{\raggedleft\small\sffamily\bfseries\@JournalInfo\\\@Archive\par}% +\vskip20pt% +{\raggedright\color{color1}\sffamily\bfseries\fontsize{20}{25}\selectfont \@PaperTitle\par}% +\vskip10pt +{\raggedright\color{color1}\sffamily\fontsize{12}{16}\selectfont \@Authors\par} +\vskip18pt% +\fcolorbox{color1}{white}{% +\parbox{\textwidth-2\fboxsep-2\fboxrule}{\centering% +\colorbox{color2!10}{% +\parbox{\textwidth-3.5\fboxsep-3.5\fboxrule}{% +\ifx\@Keywords\@empty +\sffamily\small\textbf{\abstractname}\\\@Abstract +\else +\sffamily\small\textbf{\abstractname}\\\@Abstract\\[5pt]% +\textbf{\keywordname}\\\@Keywords% +\fi +}% +}% +\vskip5pt% +\begingroup% +\raggedright\sffamily\small% +\footnotesize\@affiliation\par% +\endgroup%% +}% +}% +\vskip25pt% +}]% +}% +% --------------------------------------------------------------------- +\let\oldbibliography\thebibliography +\renewcommand{\thebibliography}[1]{% +\addcontentsline{toc}{section}{\hspace*{-\tocsep}\refname}% +\oldbibliography{#1}% +\setlength\itemsep{0pt}% +}
\ No newline at end of file diff --git a/longbow/documentation/LaTeX Documentation/parc_black_solid.png b/longbow/documentation/LaTeX Documentation/parc_black_solid.png Binary files differnew file mode 100644 index 00000000..6abcf2f4 --- /dev/null +++ b/longbow/documentation/LaTeX Documentation/parc_black_solid.png |
